Testing transactional e-mail without sending: Sandbox keys, test mode and simulated bounces

E-mail·· 61 views· 3 min read

The short answer: with a key that starts with sandbox_, nothing is sent or charged. The e-mail becomes simulated, with simulated events, and other changes (domains, templates, suppressions) are only simulated too. To rehearse bounces and complaints, send to bounce@example.com or complaint@example.com.

Sandbox and Production

sandbox_ key prod_ key
Address and operations The same The same
The e-mail Validated, but not sent Sent
Credits Not charged One per recipient
Status simulated The real status
Domains, templates, suppressions Only simulated: nothing is saved Saved

Rehearsing what goes wrong

Send to What happens
bounce@example.com Simulates a bounce: you see the bounced event and the email.bounced webhook
complaint@example.com Simulates a complaint: you see the complained event and the email.complained webhook

It is the best way to confirm your system reacts properly: it flags the address as invalid, tells the customer and does not try again.

Email Center test mode

There is one more case of simulation: while Email Center is in test mode, prod_ keys simulate too. To find out, call GET /v1/email/balance and look at test_mode: true means nothing is really sent yet.

A checklist before going live

1 A simple send with text and with html: a 201 answer and simulated status.
2 With a template: every variable filled in.
3 With an attachment: the real PDF you will send, to see that it fits the size limit.
4 A retry with the same Idempotency-Key: the e-mail is not duplicated.
5 A bounce and a complaint with the two rehearsal addresses, and your webhook receiving them.
6 Switch the key for a prod_ one. The address and operations stay the same.
In Sandbox the domain is not saved. Before your first real send, add and verify the domain for real, with the Production key or on the page in My MozOut.
Use different keys in your test environment and on your production server. That way a forgotten test never e-mails a real customer.

Want to test sending e-mail without spending credits? See the API page.

See the API page

SEE ALSO

Getting started with Email Center: turn it on, verify your domain and send your first e-mail

Sending a transactional e-mail through the API: the fields of POST /v1/email/messages

Email Center webhooks: receiving delivery, bounce and complaint events in your system

Transactional e-mail statuses: sent, delivered, bounced, complained and failed explained

Email Center API errors: email_account_required, all_recipients_suppressed and other reasons

An API key or token has leaked: what to do, in the right order

RECOMMENDED PRODUCT

Professional e-mail on your domain

Mailboxes in your company name, no adverts, with spam filtering. from £5.28/mo (3-year plan, with coupon)

See plans
Was this answer helpful? Your answer helps us improve this article.

Related Articles

E-mail 2,782 How to access your webmail You don't need to install anything to check your e-mail - the webmail works straight from your browser, on any device. A...
E-mail 2,518 How to set up your e-mail on Android Set your e-mail up once on Android and it keeps syncing in the background, on Wi-Fi or mobile data. Setting it up 1 Open...
E-mail 2,058 How to set up your e-mail on iPhone or iPad The Mail app on iPhone and iPad can hold your professional e-mail alongside any personal accounts, each syncing independ...
E-mail 2,419 How to set up your e-mail in Thunderbird Thunderbird can detect this server's settings automatically - you only need to type your name, e-mail and password. Auto...
E-mail 1,581 How to set up your e-mail in the new Outlook for Windows The new Outlook for Windows tries to configure itself automatically. If it can't, it falls back to the same manual setti...
E-mail 73 Email Center API errors: email_account_required, all_recipients_suppressed and other reasons The short answer: the HTTP code tells you the kind of problem and the details.reason field tells you the exact reason. I...