{
  "openapi": "3.0.3",
  "info": {
    "title": "InboxReadyCheck API",
    "version": "1.0.0",
    "description": "Complete REST API for email deliverability testing, authentication validation, blocklist monitoring, and infrastructure checks. Build email validation into your applications with comprehensive endpoints for SPF, DKIM, DMARC, BIMI, ARC, PTR, uptime monitoring, blocklist checking, and seed testing.",
    "termsOfService": "https://inboxreadycheck.com/terms",
    "contact": {
      "name": "InboxReadyCheck API Support",
      "email": "api@inboxreadycheck.com",
      "url": "https://inboxreadycheck.com/contact"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://inboxreadycheck.com/terms"
    }
  },
  "servers": [
    {
      "url": "https://inboxreadycheck.com/api",
      "description": "Production server"
    },
    {
      "url": "https://staging.inboxreadycheck.com/api",
      "description": "Staging server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "tags": [
    {
      "name": "Authentication",
      "description": "Email authentication validation endpoints (SPF, DKIM, DMARC, BIMI, ARC, PTR)"
    },
    {
      "name": "Monitoring",
      "description": "Infrastructure and reputation monitoring (uptime, blocklist, seed testing)"
    },
    {
      "name": "Compliance",
      "description": "Email compliance validation (CAN-SPAM, GDPR, CASL)"
    },
    {
      "name": "Content Analysis",
      "description": "HTML, link, and bounce message analysis"
    },
    {
      "name": "Full Analysis",
      "description": "Complete deliverability analysis combining all checks"
    }
  ],
  "paths": {
    "/validate/spf": {
      "post": {
        "tags": ["Authentication"],
        "summary": "Validate SPF record",
        "description": "Validates SPF record with 10-lookup limit checking, recursive include validation, and syntax error detection",
        "operationId": "validateSPF",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["domain"],
                "properties": {
                  "domain": {
                    "type": "string",
                    "description": "Domain to check SPF record for",
                    "example": "example.com"
                  },
                  "ip": {
                    "type": "string",
                    "description": "Optional IP address to verify against SPF",
                    "example": "192.0.2.1"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "SPF validation result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SPFValidationResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitExceeded"
          }
        }
      }
    },
    "/validate/dkim": {
      "post": {
        "tags": ["Authentication"],
        "summary": "Validate DKIM signature",
        "description": "Verifies DKIM signature with key length validation and body hash verification",
        "operationId": "validateDKIM",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["domain", "selector"],
                "properties": {
                  "domain": {
                    "type": "string",
                    "example": "example.com"
                  },
                  "selector": {
                    "type": "string",
                    "example": "default"
                  },
                  "emailContent": {
                    "type": "string",
                    "description": "Optional raw email content for signature verification"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "DKIM validation result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DKIMValidationResponse"
                }
              }
            }
          }
        }
      }
    },
    "/validate/dmarc": {
      "post": {
        "tags": ["Authentication"],
        "summary": "Validate DMARC policy",
        "description": "Analyzes DMARC policy with alignment testing and report destination validation",
        "operationId": "validateDMARC",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["domain"],
                "properties": {
                  "domain": {
                    "type": "string",
                    "example": "example.com"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "DMARC validation result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DMARCValidationResponse"
                }
              }
            }
          }
        }
      }
    },
    "/monitoring/uptime/check": {
      "post": {
        "tags": ["Monitoring"],
        "summary": "Run uptime check",
        "description": "Performs infrastructure uptime check for SMTP, DNS, HTTP, HTTPS, or SSL",
        "operationId": "checkUptime",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["type", "target"],
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": ["smtp", "dns", "http", "https", "ssl"],
                    "example": "smtp"
                  },
                  "target": {
                    "type": "string",
                    "description": "Hostname, IP, or URL to check",
                    "example": "smtp.gmail.com"
                  },
                  "port": {
                    "type": "integer",
                    "description": "Port number (default: 25 for SMTP, 443 for SSL)",
                    "example": 587
                  },
                  "timeout": {
                    "type": "integer",
                    "description": "Timeout in milliseconds",
                    "example": 10000
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Uptime check result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UptimeCheckResponse"
                }
              }
            }
          }
        }
      }
    },
    "/monitoring/blocklist/check": {
      "post": {
        "tags": ["Monitoring"],
        "summary": "Check blocklists",
        "description": "Checks IP address or domain across 50+ email blocklists",
        "operationId": "checkBlocklist",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["target"],
                "properties": {
                  "target": {
                    "type": "string",
                    "description": "IP address or domain to check",
                    "example": "192.0.2.1"
                  },
                  "tier": {
                    "type": "string",
                    "enum": ["free", "pro", "enterprise"],
                    "description": "Blocklist tier (free: 10 lists, pro: 30 lists, enterprise: 50+ lists)",
                    "example": "pro"
                  },
                  "concurrency": {
                    "type": "integer",
                    "description": "Number of concurrent checks",
                    "example": 10
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Blocklist check result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BlocklistCheckResponse"
                }
              }
            }
          }
        }
      }
    },
    "/monitoring/seed-test/run": {
      "post": {
        "tags": ["Monitoring"],
        "summary": "Run seed test",
        "description": "Sends email to seed accounts and measures inbox vs spam placement",
        "operationId": "runSeedTest",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["from", "subject", "html"],
                "properties": {
                  "from": {
                    "type": "string",
                    "format": "email",
                    "example": "sender@example.com"
                  },
                  "fromName": {
                    "type": "string",
                    "example": "Example Company"
                  },
                  "subject": {
                    "type": "string",
                    "example": "Test Email Subject"
                  },
                  "html": {
                    "type": "string",
                    "description": "HTML email content"
                  },
                  "text": {
                    "type": "string",
                    "description": "Plain text version"
                  },
                  "tier": {
                    "type": "string",
                    "enum": ["free", "pro", "enterprise"],
                    "description": "Seed list tier"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Seed test result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SeedTestResponse"
                }
              }
            }
          }
        }
      }
    },
    "/analyze": {
      "post": {
        "tags": ["Full Analysis"],
        "summary": "Complete deliverability analysis",
        "description": "Runs comprehensive email deliverability check including all authentication, compliance, and content validations",
        "operationId": "analyzeEmail",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["domain"],
                "properties": {
                  "domain": {
                    "type": "string",
                    "example": "example.com"
                  },
                  "html": {
                    "type": "string",
                    "description": "Email HTML content for analysis"
                  },
                  "fromEmail": {
                    "type": "string",
                    "example": "sender@example.com"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Full analysis result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FullAnalysisResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "API key for authentication. Get your key at https://inboxreadycheck.com/dashboard"
      }
    },
    "schemas": {
      "SPFValidationResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "object",
            "properties": {
              "valid": {
                "type": "boolean"
              },
              "lookups": {
                "type": "integer"
              },
              "record": {
                "type": "string"
              },
              "issues": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "DKIMValidationResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "object",
            "properties": {
              "valid": {
                "type": "boolean"
              },
              "keyLength": {
                "type": "integer"
              },
              "selector": {
                "type": "string"
              },
              "publicKey": {
                "type": "string"
              }
            }
          }
        }
      },
      "DMARCValidationResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "object",
            "properties": {
              "valid": {
                "type": "boolean"
              },
              "policy": {
                "type": "string",
                "enum": ["none", "quarantine", "reject"]
              },
              "record": {
                "type": "string"
              }
            }
          }
        }
      },
      "UptimeCheckResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "result": {
            "type": "object",
            "properties": {
              "status": {
                "type": "string",
                "enum": ["up", "down", "degraded"]
              },
              "responseTime": {
                "type": "integer"
              },
              "timestamp": {
                "type": "string",
                "format": "date-time"
              }
            }
          }
        }
      },
      "BlocklistCheckResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "summary": {
            "type": "object",
            "properties": {
              "totalChecked": {
                "type": "integer"
              },
              "listed": {
                "type": "integer"
              },
              "unlisted": {
                "type": "integer"
              }
            }
          }
        }
      },
      "SeedTestResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "summary": {
            "type": "object",
            "properties": {
              "testId": {
                "type": "string"
              },
              "inboxCount": {
                "type": "integer"
              },
              "spamCount": {
                "type": "integer"
              },
              "metrics": {
                "type": "object",
                "properties": {
                  "inboxRate": {
                    "type": "number"
                  },
                  "spamRate": {
                    "type": "number"
                  }
                }
              }
            }
          }
        }
      },
      "FullAnalysisResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "score": {
            "type": "number"
          },
          "results": {
            "type": "object"
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string"
          },
          "code": {
            "type": "string"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          }
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Bad request - invalid parameters",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Unauthorized - invalid or missing API key",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "RateLimitExceeded": {
        "description": "Rate limit exceeded",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        },
        "headers": {
          "X-RateLimit-Limit": {
            "schema": {
              "type": "integer"
            },
            "description": "Request limit per minute"
          },
          "X-RateLimit-Remaining": {
            "schema": {
              "type": "integer"
            },
            "description": "Requests remaining in current window"
          },
          "X-RateLimit-Reset": {
            "schema": {
              "type": "integer"
            },
            "description": "Unix timestamp when rate limit resets"
          }
        }
      }
    }
  }
}