API reference

Validate email addresses

POST/api/v2/email-validations

Check whether an address can receive email before you send to it, for example on a sign-up form. Works with sending and full keys.

Each check uses one validation credit from your plan. Unknown results and sandbox addresses are free.

What is checked

  1. Format: the address follows the rules mail servers accept.
  2. History: your blacklist and earlier spam complaints and hard bounces on Robust Email.
  3. Disposable domains: about 10,000 temporary email services.
  4. Domain: the domain exists and has a mail server (MX), and does not refuse all mail.
  5. Typos: common misspellings such as gmial.com come back with a suggestion.
  6. Mailbox: the recipient’s mail server is asked whether the mailbox exists. No email is sent.
  7. Catch-all: whether the domain accepts every address, which means the mailbox cannot be confirmed.

Validate one address

curl -X POST https://robustemail.com/api/v2/email-validations \
  -H "Authorization: Bearer $ROBUSTEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "jane@example.com" }'

The answer usually takes one to a few seconds, because it waits for the recipient’s mail server.

{
  "email": "jane@example.com",
  "status": "valid",
  "sub_status": "",
  "account": "jane",
  "domain": "example.com",
  "did_you_mean": null,
  "free_email": false,
  "role": false,
  "disposable": false,
  "mx_found": true,
  "mx_record": "mx1.example.com",
  "smtp": { "code": 250, "message": "250 2.1.5 OK" },
  "processed_at": "2026-10-26T09:12:40Z"
}

Statuses

statusMeaningWhat to do
validThe mailbox exists and accepts mail.Send.
invalidThe address does not exist or cannot receive mail.Do not send.
catch_allThe domain accepts every address, so this mailbox cannot be confirmed.Send with care.
unknownThe mail server gave no clear answer (greylisting, temporary errors). Free.Try again later.
do_not_mailDisposable, on your blacklist, or otherwise not worth sending to.Do not send.
abuseReported email as spam on an earlier send.Do not send.

Sub-statuses

sub_status says why. The most common values:

sub_statusWith status
mailbox_not_found, mailbox_disabled, mailbox_quota_exceededinvalid
failed_syntax_check, possible_typo, no_dns_entries, does_not_accept_mail, previously_bouncedinvalid
disposable, global_suppressiondo_not_mail
spam_complaintabuse
greylisted, antispam_system, mail_server_temporary_error, mail_server_did_not_respond, failed_smtp_connection, provider_accepts_all, dns_lookup_failedunknown

role is true for team addresses such as info@ and sales@, and free_email for providers such as Gmail and Yahoo. They are information, not reasons to reject.

Validate a batch

Send up to 10,000 addresses. They are checked in the background, grouped by domain.

curl -X POST https://robustemail.com/api/v2/email-validations/batch \
  -H "Authorization: Bearer $ROBUSTEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "emails": ["jane@example.com", "sam@example.org"] }'
{ "id": "6adf01432980f", "status": "queued", "total": 2, "processed": 0, "counts": {} }

Then ask for the results until status is done:

curl https://robustemail.com/api/v2/email-validations/batch/6adf01432980f \
  -H "Authorization: Bearer $ROBUSTEMAIL_API_KEY"
{
  "id": "6adf01432980f",
  "status": "done",
  "total": 2,
  "processed": 2,
  "counts": { "valid": 1, "invalid": 1 },
  "page": 1,
  "per_page": 1000,
  "results": [ { "email": "jane@example.com", "status": "valid", "...": "..." } ]
}

Results come 1,000 per page; add ?page=2 for the next. Batch status is one of queued, running, paused (out of credits), done, failed or cancelled. Addresses that a server greylisted are tried again after about ten minutes before the batch is done.

Test without credits

Addresses at sandbox.robustemail.dev give a fixed answer by their first word and never use credits: valid@, invalid@, catch_all@, unknown@, disposable@, do_not_mail@ and abuse@.

Errors

StatusnameWhen
422validation_erroremail or emails is missing or not the right type.
402insufficient_creditsYour plan has no validations left this month.
404not_foundNo batch with that ID for your account.

See Errors for the full list.