{
  "openapi": "3.0.0",
  "info": {
    "title": "DQVerify — Email Validation",
    "version": "1.0.0",
    "description": "Validate email addresses with deliverability, domain, and inbox checks.\n\nNo API key required for the guest endpoint. Contact [support@dqverify.com](mailto:support@dqverify.com) for a dedicated API key with higher limits."
  },
  "servers": [
    { "url": "https://api.dqverify.com/api", "description": "Production" }
  ],
  "paths": {
    "/external/validate/email": {
      "post": {
        "summary": "Validate an email address",
        "description": "Checks email format, domain existence, MX records, and inbox reachability.\n\nKey field in response: `result.IdError` — **\"01\"** = valid. Other codes: `\"02\"` email not found for domain, `\"03\"` inbox full, `\"91\"` invalid format, `\"92\"` unknown domain, `\"93\"` blacklisted, `\"95\"` disposable address.",
        "operationId": "validateEmail",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/EmailRequest" },
              "example": {
                "email": "contact@example.com"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Validation result",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/EmailResponse" },
                "example": {
                  "mode": "email_validate",
                  "email": "contact@example.com",
                  "result": {
                    "IdError": "01",
                    "eMail": "contact@example.com",
                    "eMailOrigine": "contact@example.com",
                    "Redressement": 0,
                    "CodeActivite": ""
                  }
                }
              }
            }
          },
          "429": { "description": "Guest daily limit reached (5 requests/day per IP)" },
          "422": { "description": "Invalid request body" }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "EmailRequest": {
        "type": "object",
        "required": ["email"],
        "properties": {
          "email": {
            "type": "string",
            "description": "Email address to validate",
            "example": "contact@example.com"
          }
        }
      },
      "EmailResponse": {
        "type": "object",
        "properties": {
          "mode": { "type": "string", "example": "email_validate" },
          "email": { "type": "string", "example": "contact@example.com" },
          "result": {
            "type": "object",
            "properties": {
              "IdError": {
                "type": "string",
                "description": "\"01\" = valid. \"02\" = not found for domain. \"03\" = inbox full. \"91\" = invalid format. \"92\" = unknown domain. \"93\" = blacklisted. \"95\" = disposable.",
                "example": "01"
              },
              "eMail": { "type": "string", "example": "contact@example.com" },
              "Redressement": { "type": "integer", "description": "1 if domain was corrected, 0 otherwise", "example": 0 }
            }
          }
        }
      }
    }
  }
}
