Authentication
Send your key as a bearer token on every request:
Authorization: Bearer mx_live_xxxxxxxxxxxxxxxxVerify one address
POST https://mailexchange.com/api/v1/verify
{"email": "[email protected]"}Response:
{
"email": "[email protected]",
"state": "deliverable",
"reason": "accepted_email",
"score": 100,
"accept_all": false,
"role": false,
"free": false,
"disposable": false,
"mx": "aspmx.l.google.com"
}Verify a list
Submit up to 100,000 addresses in one call. You get a list ID back straight away. Poll for status, or pass a
callback_url and we'll POST to it when the list is done.
POST https://mailexchange.com/api/v1/lists
{"emails": ["[email protected]", "[email protected]"], "callback_url": "https://you.example/hook"}
GET https://mailexchange.com/api/v1/lists/{id} # status and summary counts
GET https://mailexchange.com/api/v1/lists/{id}/results # one result per addressStates and reasons
| state | reason | What to do |
|---|---|---|
| deliverable | accepted_email | Send |
| risky | low_deliverability (catch-all), low_quality (role), disposable | Send with care. Usually leave out of cold campaigns |
| undeliverable | rejected_email, invalid_domain, invalid_email | Remove |
| unknown | unavailable_smtp, no_connect, dns_error | Retry later. The credit is refunded |
More endpoints
GET https://mailexchange.com/api/v1/lists/{id}/results?offset=0&limit=1000 # paginated JSON
GET https://mailexchange.com/api/v1/lists/{id}/results?format=csv # CSV download
DELETE https://mailexchange.com/api/v1/lists/{id} # delete list and results
GET https://mailexchange.com/api/v1/account # credit balance and usage
POST https://mailexchange.com/api/v1/feedback {"events": [{"email": "[email protected]", "event": "bounced"}]}Send us your real bounces and deliveries through /feedback. It's optional, and it makes the results better for you.
Webhooks
When a list finishes we POST {"event": "list.done", "list": {...}} to your callback_url (https only), with an
X-MX-Signature header: the hex HMAC-SHA256 of the raw body using your account's webhook secret. Check it before trusting the call.
Failed deliveries are retried after 30 seconds and 5 minutes.
Slow mail servers
Most single checks answer in a few seconds. If a mail server is slow, /verify returns 202 with
{"state": "pending", "list_id": ...}. Fetch the result later from /lists/{list_id}/results.
Credits and limits
Each unique address costs one credit, charged when you submit. Duplicates aren't charged, and unknown results are
refunded automatically when the list finishes. Requests without enough credits get 402. Rate limits are per key, and
exceeding them returns 429.