How does Mailtrap work?

How does mailtrap work? It hands your application a fake SMTP server to talk to. You swap your real mail credentials for a set of sandbox credentials, your app sends exactly as it normally would, and the message is caught in a virtual inbox instead of being delivered to anybody. That is the whole trick, and it is a good one: you can run a signup flow a hundred times against a colleague’s real address without ever landing in their mail.

That is the mechanical answer to how does mailtrap work. What follows is the setup, how to read messages back from a script, and the one thing this design can never tell you.

The mechanism, in one paragraph

SMTP is the protocol mail servers use to hand messages to each other. Mailtrap’s Email Sandbox speaks it fluently, accepts your message, and then simply stops. Nothing is forwarded. The docs give the host as sandbox.smtp.mailtrap.io on ports 25, 465, 587 or 2525, and each inbox has its own username and password, so mail sent with those credentials lands in that inbox and no other. Because your code still opens a socket, authenticates and sends a real RFC formatted message, almost everything on your side is exercised for real. Everything on the other side is not.

Step 1: Point your app at the sandbox

Open the inbox in Mailtrap, go to its Integration tab, and copy the credentials. In practice this is a four line change to a test environment file:

SMTP_HOST=sandbox.smtp.mailtrap.io
SMTP_PORT=2525
SMTP_USER=<from the Integration tab>
SMTP_PASS=<from the Integration tab>

Port 2525 is the usual pick because many hosting providers block port 25 outright. Keep these in a test only config. The mistake everyone makes once is shipping sandbox credentials to production and then wondering why customers stopped receiving mail.

Step 2: Send something, then look at it

Trigger the flow you care about and open the inbox in the browser. Alongside the HTML and plain text previews there are three panels worth knowing about, and they are the strongest part of the product:

• Spam Analysis gives a general spam score based on Apache SpamAssassin, with a table explaining each point it deducted, plus a blacklist report that checks whether your IP or domain appears on commonly used blocklists.
• HTML Check scans the markup and reports which email clients lack or only partly support each element, weighted into a market support score.
• Tech Info shows header metadata such as Message-Id, Reply-To and Bcc, along with details taken from the SMTP conversation itself.

If your question is “does this template survive Outlook” or “why does this copy read as spam”, this is the right tool and there is no need to look further.

Step 3: Automate it from your test suite

The browser view is for humans. For CI you use the API. Mailtrap splits it in two: a sandbox base URL of https://sandbox.api.mailtrap.io with POST /api/send/{sandbox_id} for putting a message in, and a separate endpoint for reading messages back out:

curl "https://mailtrap.io/api/accounts/{account_id}/inboxes/{inbox_id}/messages" \
  -H "Authorization: Bearer $MAILTRAP_API_TOKEN"

Two practical notes. There is no blocking wait, so you write a poll loop with a timeout rather than a sleep 5 and a prayer. And an inbox is shared: if four tests run in parallel against the same one, each has to filter the list for its own recipient address, or you create an inbox per test and clean up afterwards.

What a sandbox proves, and what it cannot

It proves your code assembled the right message and tried to send it. Subject, body, template variables, attachments, recipients: all real, all verifiable. That is most of what most teams need most of the time.

What it cannot prove is that the mail would arrive. No DNS is resolved, no MX record is consulted, and no receiving server ever decides whether to accept the message. That matters because SPF, DKIM and DMARC are evaluated by the receiver, not the sender. RFC 7489 is explicit that the Mail Receiver is the party that checks whether the authenticated domains align. A component that never receives anything cannot run that check.

So all of these pass in a sandbox and fail in the world:

• A DKIM key rotated out of DNS and never replaced.
• An SPF record that was never updated after you migrated providers.
• A DMARC policy of reject quietly binning your mail at the recipient.
• A provider that accepted your API call and then suppressed the send.

Where InboxDome fits, and where it does not

InboxDome takes the opposite approach: rather than intercepting mail before it leaves, it receives on a real MX over the public internet. Your message takes the same path it takes to a customer, and the API hands back what actually arrived, including the SPF, DKIM and DMARC results as the receiving server recorded them. You create a throwaway address per test with one call, wait for the message, and assert on it. If you have been reaching for a public throwaway inbox instead, our roundup of disposable inbox services worth using covers which ones hold up under an automated test. See the email testing API and the API reference for the endpoints, or testing a password reset email for a worked example.

Being equally plain about the other direction: pick Mailtrap, not us, if you want spam scoring or per client HTML compatibility, because we do neither. Pick a self hosted catcher if your CI has no outbound internet, or if policy says test data cannot leave your own infrastructure. And InboxDome is receive only by design, so it can never be your sending provider. Our comparison of the four ways to test email sets each approach side by side, including where ours is the wrong answer.

Running both is normal

The two tools are not really rivals. A sandbox is the fast inner loop: local development and unit tests, where you want zero risk of mailing a real person and you care about how the template renders. A real receiving inbox belongs in the slower suite that runs before a release, where the question is whether the mail genuinely leaves your infrastructure and passes authentication on arrival. Answering only the first question is how a DKIM key expires unnoticed for a month.