Verify a single address

POST /api/v1/verify submits one email address for validation.

Request body

Field	Type	Required	Description
email	string	yes	Address to validate
timeout	integer	no	Seconds to wait for a result (3–60; default 30)
callback_url	string	no	HTTPS URL to receive the result as a webhook

Synchronous mode (no callback_url)

The request blocks until validation completes or the timeout elapses.

POST /api/v1/verify
X-Api-Key: ev_your_key
Content-Type: application/json

{ "email": "alice@example.com", "timeout": 15 }

Completes within timeout — 200 OK:

{
  "email": "alice@example.com",
  "status": "valid",
  "sub_status": "",
  "free_email": false,
  "did_you_mean": null,
  "account": "alice",
  "domain": "example.com",
  "details": {
    "role": false,
    "disposable": false,
    "catch_all": false,
    "mx_found": true,
    "mx_record": "aspmx.l.google.com",
    "smtp_provider": "Google",
    "smtp_code": 250
  },
  "credits_remaining": 4819,
  "processed_at": "2025-06-10T14:02:11.432Z"
}

Exceeds timeout — 202 Accepted:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "pending",
  "sub_status": "timeout_exceeded",
  "result_url": "/api/v1/verify/3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Polling for results

When you receive a 202 with a result_url, poll GET /api/v1/verify/{id} until the result is ready.

GET /api/v1/verify/3fa85f64-5717-4562-b3fc-2c963f66afa6
X-Api-Key: ev_your_key

Still processing — 200 OK:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "pending"
}

Completed — 200 OK:

{
  "email": "alice@example.com",
  "status": "valid",
  ...
}

Asynchronous mode (with callback_url)

The request returns immediately with 202 Accepted. When validation completes, the full result is POSTed to your URL as a signed webhook.

POST /api/v1/verify
X-Api-Key: ev_your_key
Content-Type: application/json

{
  "email": "alice@example.com",
  "callback_url": "https://yourapp.example.com/hooks/email"
}

202 Accepted:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "pending",
  "callback_secret": "sv_a3b4c5..."
}

Store callback_secret — it is used to verify webhook signatures. See Webhooks.

Status codes

Code	Meaning
200	Validation completed synchronously
202	Accepted — async callback mode or sync timeout exceeded
400	Invalid email format or bad callback_url
401	Missing or invalid API key
402	Insufficient credits
429	Rate limit exceeded