POST /v1/check_email

Family: Verification and finder · Operation ID: v1_check_email

Access

Workspace API key: Authorization: Bearer <key>. The key is scoped to its workspace; the backend checks operation permissions and quota.

Open verification

Required scope: verify

Create a key in Developer settings. Set API_BASE_URL to the current app origin.

Request example

curl --fail-with-body -X POST "$API_BASE_URL/v1/check_email" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @request.json

Parameters

[
  {
    "description": "Optional idempotency key",
    "in": "header",
    "name": "Idempotency-Key",
    "required": false,
    "schema": {
      "nullable": true,
      "type": "string"
    }
  }
]

Request body · application/json

{
  "$ref": "#/components/schemas/CheckEmailRequest",
  "definition": {
    "description": "A request object to perform an email verification. The `to_email` field is required, all other fields are optional.",
    "properties": {
      "check_gravatar": {
        "description": "Whether to check if a Gravatar image exists for the given email.",
        "type": "boolean"
      },
      "from_email": {
        "description": "In the SMTP connection, the FROM email address.",
        "type": "string"
      },
      "gmail_verif_method": {
        "$ref": "#/components/schemas/GmailVerifMethod"
      },
      "hello_name": {
        "description": "In the SMTP connection, the EHLO hostname.",
        "type": "string"
      },
      "hotmailb2b_verif_method": {
        "$ref": "#/components/schemas/HotmailB2BVerifMethod"
      },
      "hotmailb2c_verif_method": {
        "$ref": "#/components/schemas/HotmailB2CVerifMethod"
      },
      "proxy": {
        "$ref": "#/components/schemas/CheckEmailInputProxy"
      },
      "sandbox": {
        "default": false,
        "description": "When true, returns deterministic mock results without consuming credits or making real SMTP connections.",
        "type": "boolean"
      },
      "smtp_port": {
        "description": "SMTP port to use for email validation. Defaults to 25, but 465, 587, and 2525 are sometimes also used.",
        "type": "number"
      },
      "strict_provider_rules": {
        "description": "When false, skips provider-specific syntax validation even if the provider is recognized.",
        "type": "boolean"
      },
      "to_email": {
        "description": "The email address to check.",
        "type": "string"
      },
      "yahoo_verif_method": {
        "$ref": "#/components/schemas/YahooVerifMethod"
      }
    },
    "required": [
      "to_email"
    ],
    "title": "CheckEmailRequest",
    "type": "object",
    "x-stoplight": {
      "id": "834398a8ce480"
    }
  }
}

Responses

200

{
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/CheckEmailOutput"
      }
    }
  },
  "description": "Email verification result"
}

default

{
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ErrorEnvelope"
      }
    }
  },
  "description": "Request error"
}

Download the full OpenAPI contract