Errors, credits and rate limits

Status codes

Every endpoint under https://mailexchange.com/api/v1 answers errors in the same shape. The message strings below are what the API returns today. Match on the status code, not the text.

Treat a 5xx or a network error as temporary and retry a few times with backoff, but see the note on timeouts below before blindly repeating a submit. Language examples of all this are in Python, Node.js, PHP, Ruby, Go, Java and C#.

How credits work

• Charged at submission. POST /lists takes one credit per unique address immediately. POST /verify does the same for its one address, because a single check is a one-address list.
• Duplicates are free. Addresses are trimmed and lower-cased, and repeats inside the list are dropped and not charged. The summary shows them as duplicates_removed. This applies within one list. Submitting the same address in two separate calls charges twice.
• Unknowns are refunded. When a list finishes, one credit comes back for every result with the state unknown, so you only pay for answers. For the unknown reasons see email verification statuses.
• Check your balance. GET /v1/account returns your name, credits, credits_used and the number of lists.

curl -H "Authorization: Bearer $MAILEXCHANGE_API_KEY" https://mailexchange.com/api/v1/account

Credits never expire, and the price per credit is on the pricing page. A 402 on a big list means the whole list was refused, not partly processed, so you can top up and submit again.

Rate limits

Limits are per API key over a rolling 60 second window. POST /verify counts one per request. POST /lists counts one per address in the list, with a much larger allowance, so a bulk submit is the right tool for volume. If you exceed either you get 429. A rate-limited call is rejected before any work happens, so it is always safe to repeat it.

The practical rules: reuse connections, use lists for more than a few addresses, poll every 5 to 10 seconds rather than in a tight loop, and add a retry with exponential backoff (1, 2, 4, 8 seconds is plenty). If you regularly need a higher limit, talk to us.

Handling 202 pending idempotently

Most single checks finish within seconds. If the mail server is slow, /verify waits about 20 seconds and then returns 202. That response means the check exists, has a list_id and was already charged. The safe pattern is:

1. Save the list_id from the 202 response next to your record for that address.
2. Poll GET /v1/lists/{list_id}/results?limit=1 every few seconds. While the row's state is pending, keep waiting.
3. When the state changes, use that result. If you stop waiting, look again later with the same list_id instead of calling /verify again.

# Python, using the call() helper from the Python guide
r = call("POST", "/verify", json={"email": email})
result = r.json()
if r.status_code == 202:
    store_pending(email, result["list_id"])        # remember it, never re-post
else:
    store_result(email, result)

# later, from a worker:
rows = call("GET", f"/lists/{list_id}/results", params={"limit": 1}).json()["results"]
if rows and rows[0]["state"] != "pending":
    store_result(email, rows[0])

A simple error policy

• 429: retry with backoff, up to about 4 times, then give up and queue the work.
• 402: alert a human, pause the job, resume after a top-up.
• 401: alert and stop. Retrying never fixes a bad key.
• 400, 404: a bug in the request or a wrong ID. Log the message and the payload.
• 5xx or network error: retry a few times, as above.
• Unknown or pending result: retry the address later. Unknowns are refunded, and resubmitting the address is a new charge.

Questions

Do I pay twice if I retry a /verify that returned 202?

Yes, if you post the address again, because that starts a new check. Read the result of the first one from /lists/{list_id}/results instead.

Am I charged for unknown results?

No. Unknown results are refunded automatically when the list finishes. Duplicates inside a list are never charged.

What should I do on a 429?

Wait and retry with exponential backoff. A rate-limited request does no work and costs no credits.

Related

• Email verification API reference
• Verify a list with the API
• Webhooks and callbacks
• How verification works
• All developer guides