Skip to content

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.
Send into a sandbox inbox
curl -X POST https://mailtruss.com/api/v1/emails \
-H "Authorization: Bearer ms_test_…" \
-H "Content-Type: application/json" \
-d '{ "from": "Acme <hello@acme.example>", "to": ["ana@example.com"], "subject": "Welcome", "html": "<p>Hi Ana</p>" }'
config.ts
// config: use the sandbox key outside production, the live key in production.
const apiKey = process.env.NODE_ENV === "production" ? process.env.MAILTRUSS_LIVE_KEY! : process.env.MAILTRUSS_SANDBOX_KEY!;
const mail = new MailClient({ apiKey });

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

ViewWhat it shows
PreviewThe 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, TextThe two body parts as sent.
RawThe whole message as it would travel (RFC 822), also as a .eml download.
HeadersEvery header, including the Message-ID, and any custom header and tags you set.
CheckThe 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.
AttachmentsEach 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.

.env
MAIL_HOST=smtp.mailtruss.com
MAIL_PORT=587
MAIL_USERNAME=mailtruss
MAIL_PASSWORD=ms_test_…
MAIL_ENCRYPTION=tls

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.

EndpointReturns
GET /api/v1/sandbox/messagesMessages, newest first. q searches subject, sender and recipient; unread=true; limit and after page.
GET /api/v1/sandbox/messages/:idThe bodies, headers, recipients, tags, attachment list and the check result.
GET /api/v1/sandbox/messages/:id/rawThe message as MIME text, in raw.
DELETE /api/v1/sandbox/messages/:idDeletes one message and its attachments.
DELETE /api/v1/sandbox/messagesEmpties the inbox. The keys stay.
GET, POST /api/v1/sandbox/inboxesList or create inboxes (full-access key). Creating returns the inbox's first key once, in api_key.
Examples
curl https://mailtruss.com/api/v1/sandbox/messages?limit=5 \
-H "Authorization: Bearer ms_test_…"
​
curl https://mailtruss.com/api/v1/sandbox/messages/MESSAGE_ID \
-H "Authorization: Bearer ms_test_…" # bodies, headers, cc, bcc, attachments, check
​
curl -X DELETE https://mailtruss.com/api/v1/sandbox/messages \
-H "Authorization: Bearer ms_test_…" # empty the inbox
A test
import { MailClient } from "mailtruss";
import { expect, test } from "vitest";
​
const key = process.env.MAILTRUSS_SANDBOX_KEY!;
const auth = { Authorization: `Bearer ${key}` };
​
test("signing up sends a welcome email with the right link", async () => {
await fetch("https://mailtruss.com/api/v1/sandbox/messages", { method: "DELETE", headers: auth }); // start clean
await signUp({ email: "ana@example.com" }); // your code, which sends mail
​
const { data } = await (await fetch("https://mailtruss.com/api/v1/sandbox/messages", { headers: auth })).json();
expect(data[0].subject).toBe("Welcome to Acme");
const msg = await (await fetch(`https://mailtruss.com/api/v1/sandbox/messages/${data[0].id}`, { headers: auth })).json();
expect(msg.html).toContain("https://acme.example/verify?token=");
});

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.

What changes in your code
- MAILTRUSS_API_KEY=ms_test_… # sandbox: catches mail, delivers nothing
+ MAILTRUSS_API_KEY=ms_live_… # live: delivers it
​
- MAIL_FROM="Acme <hello@acme.example>"
+ MAIL_FROM="Acme <hello@yourdomain.com>" # an address at a verified domain

Limits

PlanInboxesMessages a dayKept per inboxKept for
Free11001003 days
Starter31,00050014 days
Pro105,0001,00030 days
Business5020,0002,00090 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 429 and 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-Key is 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.

Last updated

Something wrong or unclear on this page?

Report an issue