Test mode

Test mode lets you build and check email without sending it to anyone. Use it while you write code, design templates and set up domains.

Test keys and live keys

KeyStarts withWhat it does
Testdz_test_Accepts requests and never sends email. The email is kept as caught mail.
Livedz_live_Sends real email to recipients. It counts toward your plan.

The API takes both keys the same way, and the responses have the same shape. A test send returns the status caught where a live send returns sent. Your code does not change when you switch keys. Only the delivery differs.

Keep the two keys apart. Store each one in its own environment file or environment setting, so a test key never reaches production and a live key never reaches your development machine.

Caught mail

Every email sent with a test key is kept. You can read it in two places:

  • Caught mail in the dashboard. It shows the email as a reader would see it, with its headers and the recipient, subject and time sent.
  • GET /v1/emails with the same test key. It lists caught mail in the same format as live logs, with "mode": "test". GET /v1/emails/{id} returns the full HTML, text, headers and events.

The caught email also has a warnings list. It names anything a live key would refuse. Today that is a From address that is not verified, or that uses a free mail provider. The email is still caught, so you can see the problem before you go live.

Test keys do not check whether the account is paused. Mail from a test key is caught either way.

Limits in test mode

  • Test mail does not count toward your plan.
  • A test key can catch 500 emails in each UTC day. After that, sends return 429 with test_limit_reached until the next day.
  • Recipients on your suppression list are skipped with the status suppressed, the same as in live mode. A recipient who unsubscribed from marketing mail is skipped when the email is marketing.

Move to live

When your test mail looks right:

  1. Verify your sending domain. See Domains and DNS records.
  2. Create a live key in the dashboard under API keys.
  3. Replace the test key with the live key in your production environment.
  4. Send one email to an address you own, and check the result in Logs.