Documentation
Email sandbox.
Point your app, your tests or your staging server at a sandbox inbox. Every message is caught for you to look at, and none is delivered.
How it works
- In the dashboard open Sandbox and create an inbox. It comes with a key that starts
ms_test_, shown once. - Use that key where your live key goes. The request is the same:
POST /api/v1/emails, or SMTP with the key as the password. - The message is checked like a real send (addresses, body, headers, template, attachments) and then kept in the inbox. It is never delivered, so you can use any address, including real people’s, and any
from: no domain has to be verified. - Open it in the dashboard. It appears within seconds, without a refresh.
A sandbox key is safe to share with a test environment
It can only send into its own inbox and read it. It cannot reach your domains, suppression list, webhooks, templates or other keys, and it does not count toward your plan’s API key limit.
What you can look at
| View | What it shows |
|---|---|
| Preview | The email as a mail app draws it, at desktop, tablet and mobile width, in light and an approximation of dark mode. Scripts and forms are off; images embedded with a cid: reference are shown. |
| HTML, Text | The two body parts as sent. |
| Raw | The whole message as it would travel (RFC 822), also as a .eml download. |
| Headers | Every header, including the Message-ID, and any custom header and tags you set. |
| Check | The same Will it land? checker: layout Outlook and Gmail break, images and links that will not load, the 102 KB clipping limit, spam-filter signals. |
| Attachments | Each file, downloadable. |
Over SMTP
Apps that speak SMTP (WordPress, Laravel, Rails, Django) use the same server as production with the sandbox key as the password. The message arrives in the inbox marked SMTP.
Reading the inbox from code
A test can send, then read what arrived and assert on it. A sandbox key reads its own inbox; a full-access key names one with inbox_id.
| Endpoint | Returns |
|---|---|
GET /api/v1/sandbox/messages | Messages, newest first. q searches subject, sender and recipient; unread=true; limit and after page. |
GET /api/v1/sandbox/messages/:id | The bodies, headers, recipients, tags, attachment list and the check result. |
GET /api/v1/sandbox/messages/:id/raw | The message as MIME text, in raw. |
DELETE /api/v1/sandbox/messages/:id | Deletes one message and its attachments. |
DELETE /api/v1/sandbox/messages | Empties the inbox. The keys stay. |
GET, POST /api/v1/sandbox/inboxes | List or create inboxes (full-access key). Creating returns the inbox's first key once, in api_key. |
Share a message
Open a message and choose Share to make a link for a client, a designer or a teammate without an account. It shows the rendered email only (desktop, tablet, mobile, light and dark): no headers, source, attachments, other messages or account details.
- A link works for 1, 7 or 30 days, or until you revoke it. You see how often each was opened.
- The link is shown once; only a fingerprint is stored. Anything in the email itself is visible to whoever has the link, so share it as you would the email.
- A message can have 10 active links. Deleting the message, or it expiring from the inbox, ends its links. The page is not indexed by search engines.
Going live
The inbox’s Go live tab turns “it works in the sandbox” into a checklist. It reads the messages your app sent and shows which From domains a real send would refuse, then walks through adding the domain, verifying DNS, creating a sending-only key, sending the first real email and seeing it delivered.
Limits
| Plan | Inboxes | Messages a day | Kept per inbox | Kept for |
|---|---|---|---|---|
| Free | 1 | 100 | 100 | 3 days |
| Starter | 3 | 1,000 | 500 | 14 days |
| Pro | 10 | 5,000 | 1,000 | 30 days |
| Business | 50 | 20,000 | 2,000 | 90 days |
On the Free plan, the sandbox shows the same small “Sent with Mailtruss” line that delivered mail will carry (from 4 December 2026), so a preview matches what recipients get. How the line works.
- Sandbox messages are never counted as sent email: no quota, no analytics, no suppression, no webhooks.
- “Messages a day” counts what arrived in the last 24 hours across your inboxes. Past it, a send gets a
429and nothing is captured. - An inbox keeps its newest messages; the oldest are dropped as new ones arrive, and every message is deleted after its retention period.
- A message may carry up to 2 MB of HTML, text and headers and 5 MB of attachments. An inbox can have 5 keys.
- Scheduled sends are captured at once, and
Idempotency-Keyis not applied: a retry is a second message. - The dark preview inverts colours the way many mail apps do; apps differ, so treat it as a guide. The checker reads the HTML with fixed rules and does not promise inbox placement.
Do not use a sandbox key in production
Mail sent with it is not delivered. Keep the live key for production and the sandbox key for everything else, and select between them by environment, as in the example above.