Updated November 13, 2026
Verify an email
GET /v1/verify checks one address in real time: syntax, domain, mailbox and catch-all status. Most calls return within a few seconds.
Request
| Parameter | Type | Description |
|---|---|---|
| string, required | The address to verify. URL-encode it. | |
| timeout | integer, optional | Seconds to wait before returning pending, 3 to 15. Default 15. |
| webhook_url | string, optional | Send the result here too. Overrides the account default for this call. |
Response
HTTP 200 when the check finished inside the timeout.
200 OK
{
"id": "vrf_01JD8X2T7Q",
"email": "dana.reyes@northwind.example",
"status": "done",
"result": "deliverable",
"reason": "catch_all_verified",
"score": 94,
"domain": "northwind.example",
"mx": "aspmx.l.google.com",
"flags": {
"catch_all_domain": true,
"disposable": false,
"role": false,
"free_provider": false
},
"credits_charged": 1,
"took_ms": 2140
}Response fields
| Field | Type | Description |
|---|---|---|
| id | string | Verification id, vrf_…. Use it to fetch the result again. |
| status | string | done or pending. |
| result | string | deliverable, undeliverable, risky or unknown. Null while pending. |
| reason | string | Why this result. Full list below and on /email-verification-statuses. |
| score | integer | 0–100 confidence that mail to this address will be delivered. |
| domain / mx | string | The address's domain and its primary mail server. |
| flags | object | catch_all_domain, disposable, role, free_provider, all booleans. |
| credits_charged | integer | 1 for a definite result, 0 for unknown, pending or invalid syntax. |
| took_ms | integer | Time we spent on the check, in milliseconds. |
Result and reason codes
| Result | Reason code | What it means | What to do | Credit |
|---|---|---|---|---|
| deliverable | accepted | The mail server confirmed the mailbox exists and accepts mail. | Send. | 1 credit |
| deliverable | catch_all_verified | The domain accepts all mail, and we confirmed this specific mailbox is real. | Send. Most verifiers would have marked this "unknown". | 1 credit |
| undeliverable | mailbox_not_found | The server rejected the address: no such mailbox. | Remove it. Sending will hard-bounce. | 1 credit |
| undeliverable | catch_all_no_mailbox | The domain accepts all mail, but there is no real person behind this address. | Remove it. It would be accepted, then lost or bounced later. | 1 credit |
| undeliverable | invalid_domain | The domain doesn't exist or has no mail (MX) records. | Remove it, or fix a typo like gmial.com. | 1 credit |
| undeliverable | invalid_syntax | Not a valid email address format. | Remove it. We catch these before any check runs. | Free |
| risky | disposable | A temporary inbox from a throwaway-email provider. | Block on signup forms; don't send campaigns. | 1 credit |
| risky | mailbox_full | The mailbox exists but is over quota and refusing new mail. | Hold and retry later; often an abandoned inbox. | 1 credit |
| unknown | no_response | The mail server timed out or kept greylisting us. | Re-run later. Don't send yet. | Free |
| unknown | catch_all_unresolved | A catch-all domain where we couldn't reach a confident verdict. | Re-run later, or send only from a separate, warmed domain. | Free |
Pending checks
If the check needs longer than timeout, the API returns HTTP 202 with status: "pending", result: null and a poll_url. Fetch GET /v1/verify/{id} until status is done, or receive the verification.completed webhook. No credit is used until the check finishes with a definite result.