REST API for programmatic email validation. All endpoints are under /api/v1 and require an API key.

Authentication — supply your key in the X-Api-Key request header (preferred) or as the ?api_key= query parameter (useful for quick tests; avoid in production logs where the URL may be recorded).

Rate limiting — 60 requests per minute per account. Every key on an account draws from the same budget, so adding keys does not add throughput. Exceeding the limit returns 429. Every budgeted response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, and a 429 adds Retry-After. GET /api/v1/events/stream is deliberately outside the budget and carries none of them.

Request ids — every /api/v1 response carries X-Request-Id, and every error body repeats it as request_id. Quote it in a support request.

Idempotency — the two credit-spending POSTs accept an Idempotency-Key header. A retry with the same key replays the original response (Idempotency-Replayed: true) instead of charging twice.

Webhooks — a delivery signed with X-Signature is retried up to 22 times over about 3.1 days (30s doubling to a 6h ceiling, each delay jittered ±20%). When the budget is exhausted the delivery is marked Abandoned and an in-app notification is raised.

Test mode — API keys beginning with ev_test_ return instant, canned results at zero credit cost. The outcome depends on the local part of the submitted address (e.g. valid@, invalid@, catch_all@, disposable@, role@, unknown@).

On this page

• Authentication
• Endpoints
• Schemas

Authentication

API key issued from your account dashboard. Prefix ev_ for production keys, ev_test_ for test-mode keys.

Alternative — pass the key as ?api_key=<key> in the query string when setting a header is inconvenient (e.g. browser EventSource). Avoid this in production where URLs appear in server logs.

Endpoints

Schemas

WebhookEnvelope · object

Field	Type	Description
id	string	Stable, deterministic event ID (evt_ + SHA-256 hex of the resource ID and event name). Identical across retries — use it as your idempotency key. example: evt_3a4b5c6d...
event	string	Event type. verify.completed batch.completed test example: verify.completed
created_at	string · date-time	UTC timestamp of the event. example: 2025-06-10T14:02:11.432Z
data	object	Event-specific payload: verify.completed — the full Verification object (status: complete). batch.completed — batch summary with pre-signed download URLs. Batches started with a ev_test_ key emit a real signed batch.completed webhook of the same shape (with working pre-signed URLs to the canned result files). test — { "message": "This is a test event." }.