Response & statuses
Every verification returns the same shape: a status, the reason, and the checks that produced it.
Response shape#
200 OK
{
"email": "person@example.com",
"normalized": "person@example.com",
"domain": "example.com",
"status": "valid",
"reason": "deliverable_domain",
"checks": {
"syntax": "valid",
"mx": "present",
"disposable": false,
"role": false,
"free_provider": false,
"mailbox": "not_probed"
},
"mx_hosts": ["mx1.example.com"],
"suggestion": null,
"disposable_dataset_version": "disposable-email-domains@1.0.62",
"took_ms": 42,
"credits_used": 1,
"credits_remaining": 249,
"request_id": "req_…",
"cached": false
}| Field | Type | Description |
|---|---|---|
| status | enum | valid · invalid · disposable · risky · unknown (see below). |
| reason | enum | deliverable_domain · invalid_syntax · no_mx_records · disposable_domain · role_account · dns_timeout · dns_error. |
| checks.syntax | valid | invalid | RFC-style syntax check with a typo suggestion for common providers. |
| checks.mx | present | absent | unknown | Whether the domain publishes mail-routing (MX, or implicit A) records. |
| checks.disposable | boolean | Domain is in the maintained disposable-provider dataset. |
| checks.role | boolean | Role account such as admin@, info@, support@. |
| checks.free_provider | boolean | Consumer mailbox provider such as gmail.com. |
| checks.mailbox | "not_probed" | We never connect over SMTP in v1; valid means deliverable at domain level. |
| suggestion | string | null | Likely correction, e.g. gmail.con → gmail.com. |
| credits_used | integer | 1 for a verification, 0 when an Idempotency-Key replay was served. |
| request_id | string | Echoed in the x-request-id header; quote it in support tickets. |
Statuses#
| Valid | Syntax is valid and the domain accepts email. |
| Invalid | Malformed, or the domain has no mail servers. |
| Disposable | Temporary / throwaway email provider. |
| Risky | Deliverable but a role account (admin@, info@ …). |
| Unknown | Checks could not complete (DNS timeout). Not invalid. |
Recommended policy for signup forms
Block
invalid and disposable. Accept valid. Accept risky and unknown, but send a confirmation email before trusting the address.Response headers#
| Field | Type | Description |
|---|---|---|
| x-request-id | string | Request id for support and idempotent replays. |
| x-credits-remaining | integer | Credits left after this call. |
| access-control-allow-origin | origin | Only on /v1/verify, echoing a validated origin for public keys. |
Related