API reference

Check an email

POST /v1/check: request format, authentication, response fields and disposable email detection results.

On this page

HTTP

POST /v1/check

Request

https://api.irondome.dev/v1/check

Send a Bearer API key and a JSON body with one email field.

JSON

{"email":"person@example.com"}

Requirement	Value
Authorization	`Bearer YOUR_API_KEY`
Content-Type	`application/json`
Body limit	1,024 UTF-8 bytes, including JSON syntax
Body fields	One string field: `email`

Send a known-length body with Content-Length. HTTP clients normally set this for a JSON string. Streamed bodies without a length are rejected.

Your authorized plan determines quota and billing. Additional JSON fields are rejected.

Example request

Terminal

curl --fail-with-body --request POST 'https://api.irondome.dev/v1/check' \
  --header "Authorization: Bearer $IRONDOME_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"email":"person@example.com"}'

Keep the API key in trusted server configuration. An address is checked using the service's normalization rules; clients should submit the user's address rather than implementing a separate disposable detector.

Response

A successful request returns HTTP 200:

JSON

{
  "provider": "custom",
  "valid": true,
  "disposable": false,
  "reason": "not_listed"
}

Field	Meaning
`provider`	`gmail`, `microsoft`, `icloud`, `proton`, `yahoo`, or `custom`
`valid`	The email passed syntax and normalization checks
`disposable`	Whether the detector classifies the address as disposable
`reason`	The matching rule, described below

Invalid email syntax returns HTTP 422, rather than a successful response with valid: false.

Detection reasons

Reason	Meaning
`blocked_email`	The normalized address matches a blocked address
`blocked_domain`	The domain or a parent domain matches a blocked domain
`allowed_domain`	The domain matches an allowed domain
`not_listed`	No matching rule was found

These results do not verify mailbox ownership, existence, or deliverability.

A disposable result

An illustrative blocked-domain result is still HTTP 200 because the check succeeded:

JSON

{
  "provider": "custom",
  "valid": true,
  "disposable": true,
  "reason": "blocked_domain"
}

Use disposable as your decision field. The reason explains the classification; it is not a separate success or error status.

Response headers and usage

Header	Meaning
`Content-Type`	JSON application response
`Cache-Control: no-store`	Do not cache check responses
`X-Request-ID`	Correlation ID for troubleshooting

The response does not echo the submitted email or API key. Successful checks count toward usage. An error response does not provide a usable classification; do not replace it with a cached or invented success.

Each successful request is a separate check, including repeated checks of the same email. To submit multiple addresses together, use bulk checks. Neither endpoint has an idempotency-key contract.

Connection reuse

For low overhead, use an SDK or reuse the same REST HTTP client and connection pool. Read the complete response so the connection can be reused. Avoid constructing and closing a transport for each request.

An optional health warmup can prepare the same server-side connection ahead of form submission. It is not required before checking an email.

Failures

Responses include an X-Request-ID header for troubleshooting. Keep that ID with the HTTP status and error code; avoid logging the API key or email body.

See errors for the error format. Do not automatically retry a timed-out check: it may already have completed and counted toward usage.