Testing

Available in the Medium and Large plans

This page includes test inputs and other information to make sure your test environment works before deploying to production.

Sandbox API Keys

An API request sent with a sandbox API key is automatically identified as a request in sandbox mode. All requests with sandbox keys will respond with dummy data.

You can create sandbox keys on plans with at least two API keys (Medium and Large). A sandbox key counts toward your plan's API key limit like a live key.

Requests done with sandbox keys do not count against your quota.

Please note that the requests are still shown in the graph on the dashboard. You can select only your live key if you want to filter them out.

Test email addresses

You can choose any domain. The deciding part is the part before the @. Use an ordinary domain such as example.com: on a privacy relay domain (such as privaterelay.appleid.com or duck.com) a deliverable test address gets status valid / relay_address, as a real check would.

State / Reason / Status

Email Address	State	Reason	Status	Sub-status	Recommended action
deliverable@example.com + all other email addresses	`deliverable`	`valid_mailbox`	`valid`	`null`	`send`

undeliverable@example.com undeliverable+mailbox@example.com	`undeliverable`	`invalid_mailbox`	`invalid`	`mailbox_not_found`	`suppress`
undeliverable+mx@example.com	`undeliverable`	`invalid_mx`	`invalid`	`no_dns_entries`	`suppress`
undeliverable+format@example.com	`undeliverable`	`invalid_format`	`invalid`	`failed_syntax_check`	`suppress`
undeliverable+smtp@example.com	`undeliverable`	`invalid_smtp`	`invalid`	`mailbox_not_found`	`suppress`

risky@example.com risky+quality@example.com	`risky`	`low_quality`	`risky`	`null`	`send_with_caution`
risky+deliverability@example.com	`risky`	`low_deliverability`	`risky`	`null`	`send_with_caution`

unknown@example.com unknown+smtp@example.com	`unknown`	`unavailable_smtp`	`unknown`	`mail_server_temporary_error`	`retry_later`
unknown+timeout@example.com	`unknown`	`timeout`	`unknown`	`timeout_exceeded`	`retry_later`
unknown+error@example.com	`unknown`	`unexpected_error`	`unknown`	`exception_occurred`	`retry_later`
unknown+noconnect@example.com	`unknown`	`no_connect`	`unknown`	`failed_smtp_connection`	`retry_later`
unknown+greylisted@example.com	`unknown`	`unavailable_smtp`	`unknown`	`greylisted`	`retry_later`
unknown+antispam@example.com	`unknown`	`unavailable_smtp`	`unknown`	`antispam_system`	`send_with_caution`

Any other address with a +tag, such as deliverable+news@example.com, gets the sub-status alias. The explanation is the sentence listed for the sub-status in Result Statuses. unknown+antispam stands for a permanent anti-spam block; a temporary one has the recommended action retry_later.

The sandbox answers only show the shape of a response and differ from live validation:

Live keys never return the state risky or the reason invalid_smtp, and they return low_quality and low_deliverability with the state deliverable. See State / Reason. Live validation returns the status risky only for a full mailbox, always with a sub-status.
The special cases below, except mailbox-full, keep the reason valid_mailbox. Live validation returns low_quality for a role address and low_deliverability for a disposable address or a catch-all domain. Their status, sub-status and recommended action are the ones live validation returns.
The score is always 0.64, whatever the address. See Quality Score for how live validation computes it.
smtp_check is true for the risky and unknown test addresses. Live validation sets it only for deliverable results.

Special Cases

Email Address	Response	Status	Sub-status	Recommended action
catch-all@example.com	`"catch_all": true` with `catch_all=1` in the URL, otherwise `null`	`catch_all`	`accept_all`	`send_with_caution`
mailbox-full@example.com	`"state": "deliverable"`, `"reason": "low_deliverability"`	`risky`	`mailbox_full`	`retry_later`
role@example.com	`"role": true`	`valid`	`role_based`	`send_with_caution`
disposable@example.com	`"disposable": true`	`do_not_mail`	`disposable`	`suppress`
free@example.com	`"free": true`	`valid`	`null`	`send`

As with live validation, catch-all@example.com has the status catch_all whether or not you set catch_all=1.

Bulk jobs

Bulk jobs created with a sandbox key are free and never contact a mail server: every address in the list gets the result the test addresses above define, so a list of them covers every state, reason and status. A sandbox job accepts up to 1,000 rows and usually finishes within a minute; its webhook is delivered and signed like a live one, so you can test your receiver with it. Sandbox keys and live keys have separate job lists: a sandbox key only sees and deletes jobs created with sandbox keys, and a live key only live jobs.