{
  "openapi": "3.1.0",
  "info": {
    "title": "EMAIL-CHECK.APP API Documentation",
    "version": "1.0.0",
    "description": "**EMAIL-CHECK.APP API Platform** - Real-time and bulk email validation for developers, growth teams, and product teams.\n\n**Core Service:** Validate email addresses with syntax, MX, SMTP, disposable, typo-correction, and domain intelligence checks.\n\n**Included in This Reference:** Public email validation endpoints, bulk email validation batch endpoints, API key management, usage reporting, and current identity lookup.\n\n**Authentication:** Use header `x-api-key: YOUR_API_KEY` or query parameter `?x-api-key=YOUR_API_KEY` for `/v1-get-email-details`. Use `Authorization: Bearer <token>` for API key, usage, and bulk email endpoints.\n\n**Base URL:** `https://api.email-check.app`\n\n**Support:** support@email-check.app • Complete documentation at [email-check.app](https://email-check.app)\n\n## AI Agents (MCP)\n\nThis API is also available as a hosted [MCP](https://modelcontextprotocol.io) server for AI agents at `https://api.email-check.app/mcp` — Streamable HTTP (JSON-RPC 2.0), authenticated with the same `x-api-key` header. Every tool call costs 1 credit; `account_whoami` is free. See the [MCP integration guide](https://email-check.app/guides/mcp-server) and the server card at `https://email-check.app/.well-known/mcp/server-card.json`.",
    "contact": {
      "name": "Email-Check.app Support",
      "url": "https://email-check.app/contact-us",
      "email": "support@email-check.app"
    },
    "license": {
      "name": "Commercial",
      "url": "https://email-check.app/terms-of-service"
    }
  },
  "servers": [
    {
      "url": "https://api.email-check.app",
      "description": "Production Server"
    }
  ],
  "tags": [
    {
      "name": "Email",
      "description": "Validate and enrich a single email address with syntax, MX, SMTP, disposable, typo, and domain checks."
    },
    {
      "name": "Bulk Email",
      "description": "Upload, monitor, resume, and download bulk email validation batches."
    },
    {
      "name": "API Key",
      "description": "Create, inspect, update, and delete API keys for your Email-Check.app account."
    },
    {
      "name": "API Usage",
      "description": "Review API usage metrics and export usage reports for auditing or billing analysis."
    }
  ],
  "paths": {
    "/v1-create-api-key": {
      "post": {
        "tags": ["API Key"],
        "summary": "Create API key",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ApiKeyCreateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Create Api Key response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiKeyCreateResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - Invalid input parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BadRequestError"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnauthorizedError"
                }
              }
            }
          },
          "402": {
            "description": "Payment required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentRequiredError"
                }
              }
            }
          },
          "403": {
            "description": "Access denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenError"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotFoundError"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TooManyRequestsError"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerError"
                }
              }
            }
          }
        },
        "deprecated": false,
        "description": "Generate a new API key for Email-Check.app integrations.",
        "operationId": "postV1CreateApiKey",
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "JwtTokenAuth": []
          }
        ]
      }
    },
    "/v1-delete-api-key": {
      "post": {
        "tags": ["API Key"],
        "summary": "Delete API key",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ApiKeyDeleteRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Delete Api Key response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiKeyDeleteResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - Invalid input parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BadRequestError"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnauthorizedError"
                }
              }
            }
          },
          "402": {
            "description": "Payment required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentRequiredError"
                }
              }
            }
          },
          "403": {
            "description": "Access denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenError"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotFoundError"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TooManyRequestsError"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerError"
                }
              }
            }
          }
        },
        "deprecated": false,
        "description": "Delete an API key owned by the authenticated account.",
        "operationId": "postV1DeleteApiKey",
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "JwtTokenAuth": []
          }
        ]
      }
    },
    "/v1-get-api-key-details": {
      "post": {
        "tags": ["API Key"],
        "summary": "Get API key details",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ApiKeyDetailsRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Get Api Key Details response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiKeyDetailsResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - Invalid input parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BadRequestError"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnauthorizedError"
                }
              }
            }
          },
          "402": {
            "description": "Payment required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentRequiredError"
                }
              }
            }
          },
          "403": {
            "description": "Access denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenError"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotFoundError"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TooManyRequestsError"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerError"
                }
              }
            }
          }
        },
        "deprecated": false,
        "description": "Fetch details for one API key owned by the authenticated account.",
        "operationId": "postV1GetApiKeyDetails",
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "JwtTokenAuth": []
          }
        ]
      }
    },
    "/v1-list-api-keys": {
      "post": {
        "tags": ["API Key"],
        "summary": "List API keys",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ApiKeyListRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "List Api Keys response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiKeyListResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - Invalid input parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BadRequestError"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnauthorizedError"
                }
              }
            }
          },
          "402": {
            "description": "Payment required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentRequiredError"
                }
              }
            }
          },
          "403": {
            "description": "Access denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenError"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotFoundError"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TooManyRequestsError"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerError"
                }
              }
            }
          }
        },
        "deprecated": false,
        "description": "List API keys for the authenticated Email-Check.app account.",
        "operationId": "postV1ListApiKeys",
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "JwtTokenAuth": []
          }
        ]
      }
    },
    "/v1-update-api-key": {
      "post": {
        "tags": ["API Key"],
        "summary": "Update API key",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ApiKeyUpdateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Update Api Key response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiKeyUpdateResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - Invalid input parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BadRequestError"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnauthorizedError"
                }
              }
            }
          },
          "402": {
            "description": "Payment required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentRequiredError"
                }
              }
            }
          },
          "403": {
            "description": "Access denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenError"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotFoundError"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TooManyRequestsError"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerError"
                }
              }
            }
          }
        },
        "deprecated": false,
        "description": "Update an API key name, enabled state, or service access.",
        "operationId": "postV1UpdateApiKey",
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "JwtTokenAuth": []
          }
        ]
      }
    },
    "/v1-who-am-i": {
      "get": {
        "tags": ["API Key"],
        "summary": "Get current identity",
        "responses": {
          "200": {
            "description": "Who Am I response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiKeyWhoAmIResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - Invalid input parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BadRequestError"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnauthorizedError"
                }
              }
            }
          },
          "402": {
            "description": "Payment required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentRequiredError"
                }
              }
            }
          },
          "403": {
            "description": "Access denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenError"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotFoundError"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TooManyRequestsError"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerError"
                }
              }
            }
          }
        },
        "deprecated": false,
        "description": "Return the account or API-key identity associated with the request credentials.",
        "operationId": "getV1WhoAmI",
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "JwtTokenAuth": []
          }
        ]
      }
    },
    "/v1-download-api-usage": {
      "get": {
        "tags": ["API Usage"],
        "summary": "Download API usage export",
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "required": false,
            "name": "from",
            "in": "query"
          },
          {
            "schema": {
              "type": "string"
            },
            "required": false,
            "name": "to",
            "in": "query"
          },
          {
            "schema": {
              "type": "string"
            },
            "required": false,
            "name": "service",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Download Api Usage response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiUsageDownloadResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - Invalid input parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BadRequestError"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnauthorizedError"
                }
              }
            }
          },
          "402": {
            "description": "Payment required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentRequiredError"
                }
              }
            }
          },
          "403": {
            "description": "Access denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenError"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotFoundError"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TooManyRequestsError"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerError"
                }
              }
            }
          }
        },
        "deprecated": false,
        "description": "Download usage data for reporting or billing review.",
        "operationId": "getV1DownloadApiUsage",
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "JwtTokenAuth": []
          }
        ]
      }
    },
    "/v1-get-api-usage": {
      "get": {
        "tags": ["API Usage"],
        "summary": "Get API usage",
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "required": false,
            "name": "from",
            "in": "query"
          },
          {
            "schema": {
              "type": "string"
            },
            "required": false,
            "name": "to",
            "in": "query"
          },
          {
            "schema": {
              "type": "string"
            },
            "required": false,
            "name": "service",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Get Api Usage response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiUsageGetResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - Invalid input parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BadRequestError"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnauthorizedError"
                }
              }
            }
          },
          "402": {
            "description": "Payment required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentRequiredError"
                }
              }
            }
          },
          "403": {
            "description": "Access denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenError"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotFoundError"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TooManyRequestsError"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerError"
                }
              }
            }
          }
        },
        "deprecated": false,
        "description": "Fetch API usage metrics for the authenticated account.",
        "operationId": "getV1GetApiUsage",
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "JwtTokenAuth": []
          }
        ]
      }
    },
    "/v1-get-email-details": {
      "get": {
        "tags": ["Email"],
        "summary": "Validate email address",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "email"
            },
            "required": true,
            "name": "email",
            "in": "query"
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 0,
              "exclusiveMinimum": true,
              "maximum": 10000,
              "default": 2000
            },
            "required": false,
            "name": "timeout",
            "in": "query"
          },
          {
            "schema": {
              "anyOf": [
                {
                  "type": "boolean"
                },
                {
                  "type": "string"
                }
              ],
              "default": false
            },
            "required": false,
            "name": "verifyMx",
            "in": "query"
          },
          {
            "schema": {
              "anyOf": [
                {
                  "type": "boolean"
                },
                {
                  "type": "string"
                }
              ],
              "default": false
            },
            "required": false,
            "name": "verifySmtp",
            "in": "query"
          },
          {
            "schema": {
              "anyOf": [
                {
                  "type": "boolean"
                },
                {
                  "type": "string"
                }
              ],
              "default": false
            },
            "required": false,
            "name": "detectName",
            "in": "query"
          },
          {
            "schema": {
              "anyOf": [
                {
                  "type": "boolean"
                },
                {
                  "type": "string"
                }
              ],
              "default": false
            },
            "required": false,
            "name": "suggestDomain",
            "in": "query"
          },
          {
            "schema": {
              "anyOf": [
                {
                  "type": "boolean"
                },
                {
                  "type": "string"
                }
              ],
              "default": false
            },
            "required": false,
            "name": "checkDomainAge",
            "in": "query"
          },
          {
            "schema": {
              "anyOf": [
                {
                  "type": "boolean"
                },
                {
                  "type": "string"
                }
              ],
              "default": false
            },
            "required": false,
            "name": "checkDomainRegistration",
            "in": "query"
          },
          {
            "schema": {
              "anyOf": [
                {
                  "type": "boolean"
                },
                {
                  "type": "string"
                }
              ],
              "default": false
            },
            "required": false,
            "name": "getPerformanceData",
            "in": "query"
          },
          {
            "schema": {
              "anyOf": [
                {
                  "type": "boolean"
                },
                {
                  "type": "string"
                }
              ],
              "default": false
            },
            "required": false,
            "name": "smtpDebug",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Get Email Details response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EmailDetailsResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - Invalid input parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BadRequestError"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnauthorizedError"
                }
              }
            }
          },
          "402": {
            "description": "Payment required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentRequiredError"
                }
              }
            }
          },
          "403": {
            "description": "Access denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenError"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotFoundError"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TooManyRequestsError"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerError"
                }
              }
            }
          }
        },
        "deprecated": false,
        "description": "Validate and enrich a single email address.",
        "operationId": "getV1GetEmailDetails",
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "JwtTokenAuth": []
          }
        ]
      }
    },
    "/v1-upload-email-json": {
      "post": {
        "tags": ["Bulk Email"],
        "summary": "Upload bulk email validation batch",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EmailJsonUploadRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Upload Email Json response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EmailJsonUploadResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - Invalid input parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BadRequestError"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnauthorizedError"
                }
              }
            }
          },
          "402": {
            "description": "Payment required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentRequiredError"
                }
              }
            }
          },
          "403": {
            "description": "Access denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenError"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotFoundError"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TooManyRequestsError"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerError"
                }
              }
            }
          }
        },
        "deprecated": false,
        "description": "Upload a CSV-derived email batch for bulk validation.",
        "operationId": "postV1UploadEmailJson",
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "JwtTokenAuth": []
          }
        ]
      }
    },
    "/v1-list-upload-email-json": {
      "post": {
        "tags": ["Bulk Email"],
        "summary": "List bulk email validation batches",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EmailJsonListRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "List Upload Email Json response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EmailJsonListResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - Invalid input parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BadRequestError"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnauthorizedError"
                }
              }
            }
          },
          "402": {
            "description": "Payment required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentRequiredError"
                }
              }
            }
          },
          "403": {
            "description": "Access denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenError"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotFoundError"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TooManyRequestsError"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerError"
                }
              }
            }
          }
        },
        "deprecated": false,
        "description": "List bulk email validation batches for the authenticated account.",
        "operationId": "postV1ListUploadEmailJson",
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "JwtTokenAuth": []
          }
        ]
      }
    },
    "/v1-download-email-json": {
      "post": {
        "tags": ["Bulk Email"],
        "summary": "Download bulk email validation results",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DownloadEmailDataRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Download Email Json response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EmailJsonDownloadResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - Invalid input parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BadRequestError"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnauthorizedError"
                }
              }
            }
          },
          "402": {
            "description": "Payment required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentRequiredError"
                }
              }
            }
          },
          "403": {
            "description": "Access denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenError"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotFoundError"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TooManyRequestsError"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerError"
                }
              }
            }
          }
        },
        "deprecated": false,
        "description": "Download processed records for a bulk email validation batch.",
        "operationId": "postV1DownloadEmailJson",
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "JwtTokenAuth": []
          }
        ]
      }
    },
    "/v1-resume-email-json": {
      "post": {
        "tags": ["Bulk Email"],
        "summary": "Resume bulk email validation batch",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ResumeBulkEmailJsonRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Resume Email Json response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EmailJsonResumeResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - Invalid input parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BadRequestError"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnauthorizedError"
                }
              }
            }
          },
          "402": {
            "description": "Payment required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentRequiredError"
                }
              }
            }
          },
          "403": {
            "description": "Access denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenError"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotFoundError"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TooManyRequestsError"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerError"
                }
              }
            }
          }
        },
        "deprecated": false,
        "description": "Retry or resume a stuck or failed bulk email validation batch.",
        "operationId": "postV1ResumeEmailJson",
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "JwtTokenAuth": []
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "API key authentication. Create keys under Account → API keys. Keys are scoped to the product host. The API key may also be passed as the `x-api-key` query parameter."
      },
      "JwtTokenAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-jwt-token",
        "description": "JWT session-token authentication. When both an API key and a JWT are present, the API key takes precedence."
      }
    },
    "schemas": {
      "ApiKeyCreateRequest": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 255
          },
          "services": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "isEnabled": {
            "type": "boolean"
          }
        },
        "additionalProperties": {
          "nullable": true
        },
        "summary": "Create API Key",
        "description": "Create a new API key for the authenticated user.",
        "example": {
          "name": "Production Key",
          "services": ["email"],
          "isEnabled": true
        }
      },
      "ApiKeyCreateResponse": {
        "type": "object",
        "properties": {
          "_id": {
            "anyOf": [
              {
                "type": "string",
                "format": "objectId",
                "example": "507f1f77bcf86cd799439011",
                "description": "MongoDB ObjectId (24-character hex string)"
              },
              {
                "type": "string",
                "pattern": "^[a-fA-F0-9]{24}$"
              }
            ]
          },
          "userId": {
            "anyOf": [
              {
                "type": "string",
                "format": "objectId",
                "example": "507f1f77bcf86cd799439011",
                "description": "MongoDB ObjectId (24-character hex string)"
              },
              {
                "type": "string",
                "pattern": "^[a-fA-F0-9]{24}$"
              }
            ]
          },
          "apiKey": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "environment": {
            "type": "string"
          },
          "services": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "isEnabled": {
            "type": "boolean"
          },
          "host": {
            "type": "string"
          },
          "note": {
            "type": "string"
          },
          "meta": {
            "nullable": true
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "example": "2025-01-01T12:00:00.000Z"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "example": "2025-01-01T12:00:00.000Z"
          }
        },
        "required": ["_id", "userId", "isEnabled", "host", "createdAt", "updatedAt"],
        "description": "Created API key document."
      },
      "ApiKeyDeleteRequest": {
        "type": "object",
        "properties": {
          "_id": {
            "type": "string",
            "pattern": "^[a-fA-F0-9]{24}$"
          }
        },
        "required": ["_id"],
        "additionalProperties": {
          "nullable": true
        },
        "summary": "Delete Api Key",
        "description": "Request schema for Delete Api Key."
      },
      "ApiKeyDeleteResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          }
        },
        "required": ["success"],
        "description": "Response schema for Delete Api Key."
      },
      "ApiKeyDetailsRequest": {
        "type": "object",
        "properties": {
          "_id": {
            "type": "string",
            "pattern": "^[a-fA-F0-9]{24}$"
          }
        },
        "required": ["_id"],
        "additionalProperties": {
          "nullable": true
        },
        "summary": "Get API Key Details",
        "description": "Fetch details for an API key owned by the authenticated user.",
        "example": {
          "_id": "507f1f77bcf86cd799439011"
        }
      },
      "ApiKeyDetailsResponse": {
        "type": "object",
        "nullable": true,
        "properties": {
          "_id": {
            "anyOf": [
              {
                "type": "string",
                "format": "objectId",
                "example": "507f1f77bcf86cd799439011",
                "description": "MongoDB ObjectId (24-character hex string)"
              },
              {
                "type": "string",
                "pattern": "^[a-fA-F0-9]{24}$"
              }
            ]
          },
          "userId": {
            "anyOf": [
              {
                "type": "string",
                "format": "objectId",
                "example": "507f1f77bcf86cd799439011",
                "description": "MongoDB ObjectId (24-character hex string)"
              },
              {
                "type": "string",
                "pattern": "^[a-fA-F0-9]{24}$"
              }
            ]
          },
          "apiKey": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "environment": {
            "type": "string"
          },
          "services": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "isEnabled": {
            "type": "boolean"
          },
          "host": {
            "type": "string"
          },
          "note": {
            "type": "string"
          },
          "meta": {
            "nullable": true
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "example": "2025-01-01T12:00:00.000Z"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "example": "2025-01-01T12:00:00.000Z"
          }
        },
        "required": ["_id", "userId", "isEnabled", "host", "createdAt", "updatedAt"],
        "description": "API key details, or null when no matching key is found.",
        "example": {
          "_id": "507f1f77bcf86cd799439011",
          "userId": "507f1f77bcf86cd799439012",
          "apiKey": "507f1f77bcf86cd799439012-abc123",
          "name": "Production Key",
          "environment": "production",
          "services": ["email"],
          "isEnabled": true,
          "host": "email-check.app",
          "note": "Used by production workload",
          "meta": {
            "reqIpAddress": "127.0.0.1"
          },
          "createdAt": "2025-01-01T12:00:00.000Z",
          "updatedAt": "2025-01-01T12:00:00.000Z"
        }
      },
      "ApiKeyListRequest": {
        "type": "object",
        "properties": {},
        "additionalProperties": {
          "nullable": true
        },
        "summary": "List Api Keys",
        "description": "Request schema for List Api Keys."
      },
      "ApiKeyListResponse": {
        "type": "object",
        "properties": {
          "list": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ApiKeyModel"
            }
          }
        },
        "required": ["list"],
        "description": "Response schema for List Api Keys."
      },
      "ApiKeyModel": {
        "type": "object",
        "properties": {
          "_id": {
            "anyOf": [
              {
                "type": "string",
                "format": "objectId",
                "example": "507f1f77bcf86cd799439011",
                "description": "MongoDB ObjectId (24-character hex string)"
              },
              {
                "type": "string",
                "pattern": "^[a-fA-F0-9]{24}$"
              }
            ]
          },
          "userId": {
            "anyOf": [
              {
                "type": "string",
                "format": "objectId",
                "example": "507f1f77bcf86cd799439011",
                "description": "MongoDB ObjectId (24-character hex string)"
              },
              {
                "type": "string",
                "pattern": "^[a-fA-F0-9]{24}$"
              }
            ]
          },
          "apiKey": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "environment": {
            "type": "string"
          },
          "services": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "isEnabled": {
            "type": "boolean"
          },
          "host": {
            "type": "string"
          },
          "note": {
            "type": "string"
          },
          "meta": {
            "nullable": true
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "example": "2025-01-01T12:00:00.000Z"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "example": "2025-01-01T12:00:00.000Z"
          }
        },
        "required": ["_id", "userId", "isEnabled", "host", "createdAt", "updatedAt"],
        "description": "API key document stored for a user and host."
      },
      "ApiKeyUpdateRequest": {
        "type": "object",
        "properties": {
          "_id": {
            "type": "string",
            "pattern": "^[a-fA-F0-9]{24}$"
          },
          "name": {
            "type": "string",
            "maxLength": 255
          },
          "environment": {
            "type": "string"
          },
          "services": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "isEnabled": {
            "type": "boolean"
          }
        },
        "required": ["_id"],
        "additionalProperties": {
          "nullable": true
        },
        "summary": "Update Api Key",
        "description": "Request schema for Update Api Key."
      },
      "ApiKeyUpdateResponse": {
        "type": "object",
        "nullable": true,
        "properties": {
          "_id": {
            "anyOf": [
              {
                "type": "string",
                "format": "objectId",
                "example": "507f1f77bcf86cd799439011",
                "description": "MongoDB ObjectId (24-character hex string)"
              },
              {
                "type": "string",
                "pattern": "^[a-fA-F0-9]{24}$"
              }
            ]
          },
          "userId": {
            "anyOf": [
              {
                "type": "string",
                "format": "objectId",
                "example": "507f1f77bcf86cd799439011",
                "description": "MongoDB ObjectId (24-character hex string)"
              },
              {
                "type": "string",
                "pattern": "^[a-fA-F0-9]{24}$"
              }
            ]
          },
          "apiKey": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "environment": {
            "type": "string"
          },
          "services": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "isEnabled": {
            "type": "boolean"
          },
          "host": {
            "type": "string"
          },
          "note": {
            "type": "string"
          },
          "meta": {
            "nullable": true
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "example": "2025-01-01T12:00:00.000Z"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "example": "2025-01-01T12:00:00.000Z"
          }
        },
        "required": ["_id", "userId", "isEnabled", "host", "createdAt", "updatedAt"],
        "description": "Updated API key document, or null when no matching key was found.",
        "example": {
          "_id": "507f1f77bcf86cd799439011",
          "userId": "507f1f77bcf86cd799439012",
          "apiKey": "507f1f77bcf86cd799439012-abc123",
          "name": "Production Key",
          "environment": "production",
          "services": ["email"],
          "isEnabled": true,
          "host": "email-check.app",
          "note": "Used by production workload",
          "meta": {
            "reqIpAddress": "127.0.0.1"
          },
          "createdAt": "2025-01-01T12:00:00.000Z",
          "updatedAt": "2025-01-01T12:00:00.000Z"
        }
      },
      "ApiKeyWhoAmIResponse": {
        "type": "object",
        "properties": {
          "userId": {
            "type": "string",
            "nullable": true
          },
          "email": {
            "type": "string",
            "nullable": true
          },
          "username": {
            "type": "string",
            "nullable": true
          },
          "reqIpAddress": {
            "type": "string",
            "nullable": true
          },
          "reqIpCountry": {
            "type": "string",
            "nullable": true
          },
          "reqUserAgent": {
            "type": "string",
            "nullable": true
          }
        },
        "description": "Response schema for Who Am I."
      },
      "ApiUsageDownloadResponse": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string"
          },
          "filename": {
            "type": "string"
          },
          "contentType": {
            "type": "string"
          }
        },
        "required": ["url", "filename", "contentType"],
        "description": "Response schema for Download Api Usage."
      },
      "ApiUsageGetResponse": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "date": {
              "type": "string"
            },
            "service": {
              "type": "string"
            },
            "count": {
              "type": "number"
            },
            "userId": {
              "type": "string"
            }
          },
          "required": ["date", "service", "count", "userId"]
        },
        "description": "Daily API usage rows for the authenticated user.",
        "example": [
          {
            "date": "2026-03-12",
            "service": "get-email-details",
            "count": 14,
            "userId": "507f1f77bcf86cd799439011"
          }
        ]
      },
      "BadRequestError": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "example": "VALIDATION_ERROR",
            "description": "Error code identifier"
          },
          "message": {
            "type": "string",
            "example": "Invalid request parameters",
            "description": "Human-readable error message"
          },
          "issues": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ErrorIssue"
            },
            "default": [],
            "description": "Validation or structured error details."
          }
        },
        "required": ["error", "message"]
      },
      "DownloadEmailDataRequest": {
        "type": "object",
        "properties": {
          "batchId": {
            "type": "string",
            "minLength": 1
          }
        },
        "required": ["batchId"],
        "additionalProperties": {
          "nullable": true
        },
        "summary": "Download Email Batch Data",
        "description": "Get full processed email records for a batch ID.",
        "example": {
          "batchId": "batch_123"
        }
      },
      "EmailDetailsResponse": {
        "type": "object",
        "properties": {
          "email": {
            "type": "string"
          },
          "validMx": {
            "type": "boolean",
            "nullable": true
          },
          "validSmtp": {
            "type": "boolean",
            "nullable": true
          },
          "validFormat": {
            "type": "boolean"
          },
          "isDisposable": {
            "type": "boolean"
          },
          "isFree": {
            "type": "boolean"
          },
          "mxRecords": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "detectedName": {
            "type": "object",
            "properties": {
              "firstName": {
                "type": "string"
              },
              "lastName": {
                "type": "string"
              },
              "confidence": {
                "type": "number"
              }
            }
          },
          "domainSuggestion": {
            "type": "object",
            "properties": {
              "original": {
                "type": "string"
              },
              "suggested": {
                "type": "string"
              },
              "confidence": {
                "type": "number"
              }
            }
          },
          "domainAge": {
            "type": "object",
            "properties": {
              "ageInDays": {
                "type": "number"
              },
              "createdDate": {
                "type": "string"
              },
              "isValid": {
                "type": "boolean"
              }
            }
          },
          "domainRegistration": {
            "nullable": true
          },
          "score": {
            "type": "number"
          },
          "performance": {
            "nullable": true
          },
          "smtpDebug": {
            "type": "object",
            "properties": {
              "port": {
                "type": "number"
              },
              "responseCode": {
                "type": "number"
              },
              "enhancedStatus": {
                "type": "string"
              },
              "reason": {
                "type": "string"
              },
              "source": {
                "type": "string"
              },
              "isCatchAll": {
                "type": "boolean"
              },
              "provider": {
                "type": "string"
              },
              "transcript": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "commands": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "error": {
                "type": "string"
              }
            }
          },
          "error": {
            "type": "string"
          }
        },
        "required": ["email", "validMx", "validSmtp", "validFormat", "isDisposable", "isFree"],
        "description": "Email validation details including format, deliverability, and optional enrichment signals.",
        "example": {
          "email": "alice@example.com",
          "validFormat": true,
          "validMx": true,
          "validSmtp": null,
          "isDisposable": false,
          "isFree": false
        }
      },
      "EmailJsonDownloadResponse": {
        "type": "object",
        "properties": {
          "_id": {
            "type": "string",
            "format": "objectId",
            "example": "507f1f77bcf86cd799439011",
            "description": "MongoDB ObjectId (24-character hex string)"
          },
          "fileName": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": ["pending", "processing", "completed", "failed"]
          },
          "records": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EmailRecord"
            }
          },
          "totalRecords": {
            "type": "number"
          },
          "validRecords": {
            "type": "number"
          },
          "invalidRecords": {
            "type": "number"
          },
          "fileColumns": {
            "nullable": true
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "example": "2025-01-01T12:00:00.000Z"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "example": "2025-01-01T12:00:00.000Z"
          }
        },
        "required": [
          "_id",
          "fileName",
          "status",
          "records",
          "totalRecords",
          "validRecords",
          "invalidRecords",
          "createdAt",
          "updatedAt"
        ],
        "description": "Processed email batch payload.",
        "example": {
          "_id": "507f1f77bcf86cd799439011",
          "fileName": "emails.json",
          "status": "completed",
          "records": [],
          "totalRecords": 0,
          "validRecords": 0,
          "invalidRecords": 0,
          "fileColumns": {},
          "createdAt": "2025-01-01T12:00:00.000Z",
          "updatedAt": "2025-01-01T12:00:00.000Z"
        }
      },
      "EmailJsonListRequest": {
        "type": "object",
        "properties": {
          "batchId": {
            "type": "string"
          },
          "page": {
            "type": "integer",
            "minimum": 0,
            "exclusiveMinimum": true,
            "default": 1
          },
          "limit": {
            "type": "integer",
            "minimum": 0,
            "exclusiveMinimum": true,
            "maximum": 100,
            "default": 20
          },
          "status": {
            "type": "string",
            "enum": ["pending", "processing", "completed", "failed"]
          }
        },
        "additionalProperties": {
          "nullable": true
        },
        "summary": "List Uploaded Email JSON Batches",
        "description": "List paginated email upload batches for the authenticated user.",
        "example": {
          "page": 1,
          "limit": 20,
          "status": "completed"
        }
      },
      "EmailJsonListResponse": {
        "type": "object",
        "properties": {
          "list": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "_id": {
                  "type": "string",
                  "format": "objectId",
                  "example": "507f1f77bcf86cd799439011",
                  "description": "MongoDB ObjectId (24-character hex string)"
                },
                "batchId": {
                  "type": "string"
                },
                "fileName": {
                  "type": "string"
                },
                "status": {
                  "type": "string",
                  "enum": ["pending", "processing", "completed", "failed"]
                },
                "totalRecords": {
                  "type": "number"
                },
                "processedRecords": {
                  "type": "number"
                },
                "validRecords": {
                  "type": "number"
                },
                "invalidRecords": {
                  "type": "number"
                },
                "createdAt": {
                  "type": "string",
                  "format": "date-time",
                  "example": "2025-01-01T12:00:00.000Z"
                },
                "updatedAt": {
                  "type": "string",
                  "format": "date-time",
                  "example": "2025-01-01T12:00:00.000Z"
                },
                "errorMessage": {
                  "type": "string"
                },
                "liveness": {
                  "type": "object",
                  "properties": {
                    "isStuck": {
                      "type": "boolean"
                    },
                    "staleForMs": {
                      "type": "number"
                    },
                    "stuckThresholdMs": {
                      "type": "number"
                    }
                  },
                  "required": ["isStuck", "staleForMs", "stuckThresholdMs"]
                }
              },
              "required": [
                "_id",
                "batchId",
                "fileName",
                "status",
                "totalRecords",
                "processedRecords",
                "validRecords",
                "invalidRecords",
                "createdAt",
                "updatedAt",
                "liveness"
              ]
            }
          },
          "pagination": {
            "type": "object",
            "properties": {
              "currentPage": {
                "type": "number"
              },
              "totalPages": {
                "type": "number"
              },
              "totalRecords": {
                "type": "number"
              },
              "hasNext": {
                "type": "boolean"
              },
              "hasPrev": {
                "type": "boolean"
              }
            },
            "required": ["currentPage", "totalPages", "totalRecords", "hasNext", "hasPrev"]
          }
        },
        "required": ["list", "pagination"],
        "description": "Paginated email upload batches.",
        "example": {
          "list": [],
          "pagination": {
            "currentPage": 1,
            "totalPages": 0,
            "totalRecords": 0,
            "hasNext": false,
            "hasPrev": false
          }
        }
      },
      "EmailJsonResumeResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "batchId": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": ["resumed", "completed", "no-pending", "not-stuck"]
          },
          "chunksEnqueued": {
            "type": "number"
          },
          "pendingRecords": {
            "type": "number"
          },
          "resetFailedRecords": {
            "type": "number"
          }
        },
        "required": ["success", "batchId", "status", "chunksEnqueued", "pendingRecords", "resetFailedRecords"],
        "description": "Outcome of an email batch resume request."
      },
      "EmailJsonUploadRequest": {
        "type": "object",
        "properties": {
          "jsonData": {
            "nullable": true
          },
          "emailField": {
            "nullable": true
          },
          "fileName": {
            "nullable": true
          },
          "fileColumns": {
            "nullable": true
          },
          "timeout": {
            "type": "integer",
            "minimum": 0,
            "exclusiveMinimum": true,
            "maximum": 10000,
            "default": 2000
          },
          "verifyMx": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "string"
              }
            ]
          },
          "verifySmtp": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "string"
              }
            ]
          },
          "detectName": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "string"
              }
            ]
          },
          "suggestDomain": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "string"
              }
            ]
          },
          "checkDomainAge": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "string"
              }
            ]
          },
          "checkDomainRegistration": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "string"
              }
            ]
          }
        },
        "additionalProperties": {
          "nullable": true
        },
        "summary": "Upload Email Json",
        "description": "Request schema for Upload Email Json."
      },
      "EmailJsonUploadResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "batchId": {
            "type": "string"
          },
          "totalRecords": {
            "type": "number"
          },
          "processedRecords": {
            "type": "number"
          },
          "validRecords": {
            "type": "number"
          },
          "invalidRecords": {
            "type": "number"
          },
          "status": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "batchId",
          "totalRecords",
          "processedRecords",
          "validRecords",
          "invalidRecords",
          "status"
        ],
        "description": "Response schema for Upload Email Data."
      },
      "EmailRecord": {
        "type": "object",
        "properties": {
          "emailAddress": {
            "type": "string"
          },
          "isValid": {
            "type": "boolean"
          },
          "validationStatus": {
            "type": "string"
          },
          "validationDetails": {
            "nullable": true
          },
          "error": {
            "type": "string"
          },
          "originalData": {
            "nullable": true
          }
        },
        "required": ["emailAddress", "isValid", "validationStatus"],
        "additionalProperties": {
          "nullable": true
        },
        "description": "Single processed email validation result row."
      },
      "ErrorIssue": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "path": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "array",
                "items": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "number"
                    }
                  ]
                }
              }
            ]
          }
        },
        "additionalProperties": {
          "nullable": true
        }
      },
      "ForbiddenError": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "example": "ACCESS_DENIED",
            "description": "Error code identifier"
          },
          "message": {
            "type": "string",
            "example": "You do not have permission to perform this action",
            "description": "Human-readable error message"
          },
          "issues": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ErrorIssue"
            },
            "default": [],
            "description": "Validation or structured error details."
          }
        },
        "required": ["error", "message"]
      },
      "InternalServerError": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "example": "INTERNAL_SERVER_ERROR",
            "description": "Error code identifier"
          },
          "message": {
            "type": "string",
            "example": "An unexpected error occurred",
            "description": "Human-readable error message"
          },
          "issues": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ErrorIssue"
            },
            "default": [],
            "description": "Validation or structured error details."
          }
        },
        "required": ["error", "message"]
      },
      "NotFoundError": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "example": "NOT_FOUND",
            "description": "Error code identifier"
          },
          "message": {
            "type": "string",
            "example": "The requested resource was not found",
            "description": "Human-readable error message"
          },
          "issues": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ErrorIssue"
            },
            "default": [],
            "description": "Validation or structured error details."
          }
        },
        "required": ["error", "message"]
      },
      "PaymentRequiredError": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "example": "PAYMENT_REQUIRED",
            "description": "Error code identifier"
          },
          "message": {
            "type": "string",
            "example": "Insufficient credits",
            "description": "Human-readable error message"
          },
          "issues": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ErrorIssue"
            },
            "default": [],
            "description": "Validation or structured error details."
          }
        },
        "required": ["error", "message"]
      },
      "ResumeBulkEmailJsonRequest": {
        "type": "object",
        "properties": {
          "batchId": {
            "type": "string",
            "minLength": 1
          },
          "stuckAfterMs": {
            "type": "integer",
            "nullable": true,
            "minimum": 0
          }
        },
        "required": ["batchId"],
        "summary": "Resume stuck or failed bulk email validation batch",
        "description": "Re-enqueues chunk jobs for records still pending, resets dead-lettered records, and finalises the batch if no work remains.",
        "example": {
          "batchId": "67c0f0a8d12bdb8f1c0e7e9a",
          "stuckAfterMs": 300000
        }
      },
      "TooManyRequestsError": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "example": "RATE_LIMIT_EXCEEDED",
            "description": "Error code identifier"
          },
          "message": {
            "type": "string",
            "example": "Too many requests, please try again later",
            "description": "Human-readable error message"
          },
          "issues": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ErrorIssue"
            },
            "default": [],
            "description": "Validation or structured error details."
          }
        },
        "required": ["error", "message"]
      },
      "UnauthorizedError": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "example": "AUTHENTICATION_REQUIRED",
            "description": "Error code identifier"
          },
          "message": {
            "type": "string",
            "example": "Authentication token is required",
            "description": "Human-readable error message"
          },
          "issues": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ErrorIssue"
            },
            "default": [],
            "description": "Validation or structured error details."
          }
        },
        "required": ["error", "message"]
      }
    }
  },
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "JwtTokenAuth": []
    }
  ]
}
