EmailValidator Public API

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 and POST /api/v1/results/delete_all accept an Idempotency-Key header. A retry with the same key replays the original response (Idempotency-Replayed: true) instead of charging twice.

Deletion — a stored result can be erased on demand with DELETE /api/v1/verify/{id}, DELETE /api/v1/verify/batch/{id} or POST /api/v1/results/delete_all. Deletion is immediate and irreversible, is never refunded, and needs the delete scope — which no key already issued holds unless it was asked for by name.

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@).

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.

Scopes — a key can be narrowed to part of the surface. Each operation's 403 description names the scope that route requires.

A key created without naming any scope holds read and verify — and not delete. That default is exactly what unnarrowed keys held before delete existed, so no key already in your account reaches a delete route, including every key created before scopes existed at all. Ask for delete by name when you create the key; scopes are chosen at creation and an existing key cannot be widened.

Endpoints