The email Sandbox

The Sandbox is a set of fake inboxes for the mail your application sends while you are building it. Your code sends exactly as it will in production, over SMTP or through the API, and every message lands here instead of in a real person's inbox.

Nothing in the Sandbox is ever delivered. That makes it safe to point a development database full of real customer addresses at it, to run a test suite that sends a hundred messages, or to try a template on a colleague's address without them getting it.

It needs no verified domain and no sender. A brand-new account can send its first test email within a minute.

Each sandbox inbox has one SMTP login: a username starting sbx_ and a password. Unlike live SMTP credentials, you can view the password again at any time: it can only drop mail into your sandbox, never deliver it. Point your app at the sandbox host on port 2525 (STARTTLS) or 2465 (TLS) with that login, and whatever it sends appears in the inbox within a second or two.

An API key created with Mode: Test does the same for the HTTP API. A send with a test key is checked exactly like a live one, including the sender, so it fails where a live send would. It then goes into your default inbox instead of out to the internet.

Each message can be read as the recipient would see it (at phone, tablet and desktop widths), as plain text, as HTML source, as the raw .eml, header by header, and with its attachments. The Events tab shows what would have happened next: accepted, then delivered, or a simulated bounce or complaint.

Remote images are off when you open a message. A remote image is how tracking pixels work, and loading one would tell your analytics that a test message was opened. Turn them on per message when you want to check the images themselves.

Sandbox webhooks are separate from your live webhooks and live on the Sandbox's own Webhooks tab. They send the same payload in the same format, signed with their own secret, and every call carries "environment": "sandbox". A live webhook never receives a sandbox event.

To test failure handling, send to a simulator address:

• bounce@sim.mailyte.com: a hard bounce
• softbounce@sim.mailyte.com: a temporary failure
• complaint@sim.mailyte.com: a spam complaint
• suppressed@sim.mailyte.com: a refusal because the address is suppressed

These are simulated. Nothing is added to your suppression list, and your live statistics and bills never see a sandbox message.

Limits. Each inbox keeps its newest 50 messages for up to 30 days, whichever limit is reached first; you can lower either in the inbox's settings. An organization can have 3 inboxes and send 1,000 sandbox messages a month. The Sandbox is free on every plan and never uses sending credits.

To send your first test email

1. Open Sandbox in the sidebar and choose Create my sandbox.
2. Pick your framework from the tabs and paste the settings into your app's .env or mail configuration.
3. Send an email from your app. The page opens it as soon as it arrives.

To make a sandbox key from Sending

1. Go to Sending and open the SMTP Credentials tab.
2. Choose Create Credential, and pick Sandbox under Environment.
3. Name it after the place it will be used, such as staging. This creates an inbox of the same name.

To use the API instead of SMTP

1. Go to Developer, open API Keys, and create a key with Mode: Test and the messages:send scope.
2. Use it exactly as you would a live key. Messages go to your default inbox, which you can change in an inbox's Settings.

To receive sandbox webhooks

1. Open Sandbox, then the Webhooks tab, and choose New webhook.
2. Enter your staging endpoint, or use Copy from a live webhook to start from one you already have.
3. Save the signing secret, then choose Send test event and check the response under Deliveries.

Your app says authentication failed. Check you are using the sandbox inbox's sbx_ username and its password, on port 2525 or 2465. A live SMTP credential does not work on the sandbox, and a sandbox login does not work for real sending. To see the password again, open the inbox and choose Credentials. If it may have leaked, or the inbox is older than this feature and shows no password, reset them there.

Nothing arrives. Check the host and port first, then that your app uses STARTTLS on 2525. If your code catches mail errors silently, log them: a refusal from the sandbox says why in plain words.

Messages are refused as over the limit. The organization has used its 1,000 sandbox messages this month, a message is over 10 MB, or it has more than 50 recipients. The usage line at the top of the Sandbox shows the month's count.

Old messages disappeared. An inbox keeps its newest messages up to its limit, and deletes anything older than its retention. That is on purpose, and the line under the inbox name always says what the current limits are.

A test API send was refused. Test keys check everything a live send checks, including a verified sender. Fix it the way you would for a live send, which is the point.

The email's images are missing. Remote images are blocked until you turn them on for that message.

• Senders and SMTP credentials: the live version of the same settings
• API keys: creating a key with Mode: Test
• Webhooks: the live webhooks a sandbox webhook mirrors
• Go to Sandbox