Testing email flows with a real inbox
A test of an email flow creates a fresh inbox for the run, triggers the sign-up or reset under test, waits for the message, and asserts on the code and the link in it. The risk is the inbox itself: shared between runs it mixes up their codes, and because its address is real, anyone can write to it.
Updated
How to test an email flow end to end
An end-to-end email test uses a real inbox: the test signs up with the inbox address, waits for the message, and asserts on what arrived. The inbox has a real address, so the test covers real delivery and not a mock.
- Create an inbox for the run. A
clientIdmakes creation idempotent, so a retry of the same run gets the same inbox. - Run the flow under test with the inbox address.
- Wait for a message with a code, starting from the moment the inbox was created.
- Assert on
extracted.codesandextracted.verify_links, which are filled in on arrival.
const inbox = await mail.inboxes.create({ name: `run-${runId}`, clientId: `run-${runId}` });
await signUp(inbox.address); // the flow under test
const msg = await mail.inboxes.wait(inbox.id, { hasCode: true, after: inbox.created_at });
expect(msg?.extracted.verify_links[0]).toContain("trotta.io/ confirm");Here mail is the client from the trotta-mail package. The wait returns the next delivered message, or null when its timeout passes: 30 seconds unless you set timeout. With hasCode, the wait returns only mail that carries a code. The sample message carries a code and a link. For a flow that sends a link alone, leave hasCode out and filter by from or subject.
This job has no MCP sample. A QA agent in an MCP client does the same steps with the create_inbox and wait_for_message tools.
The message the test reads
The job has one sample message, a confirmation email, and it got a deliver verdict. There is no attack in this job. The verdict below is the one the live engine gave on November 20, 2026.
The message comes from Trotta at no-reply@trotta.io, to run-8812@trotta.email, with the subject "Confirm your email". It carries the code 604381 and a confirmation link on trotta.io.
| Message | Verdict | Summary, as the engine wrote it |
|---|---|---|
| Confirm your email | deliver, level safe | No threats found. |
The engine read 604381 as a one-time code and the trotta.io link as a verify link, and marked the message as automated. Those two values are what the test asserts on.
A delivered message also carries its SPF, DKIM and DMARC results in verdict.auth, so a test can assert that your mail authenticates. See SPF, DKIM and DMARC.
In a test inbox that accepts first and checks after
A test inbox that accepts mail first and checks after is exposed like any inbox, because its address is real and anyone can write to it. When a QA agent reads that inbox, whatever lands there is read by a model with access to your test environment. In a Trotta Mail inbox the wait returns delivered mail, and held mail never reaches it.
A shared test inbox adds a problem that screening does not solve: two runs read each other's codes, or an old code satisfies a new test. A fresh inbox per run solves that one.
Setting up email tests well
An email test needs a fresh inbox per run, a wait that starts at the right moment, and assertions on parsed fields.
- A fresh inbox per run. Name it after the run id and pass the same value as
clientId. Parallel runs never share an address. - A wait that starts at inbox creation.
aftertakes a message id or a time, so a message from an earlier step is never returned. - A filter when the flow sends several emails. Add
fromorsubjectto the wait, orhasCodefor the message with the code. - Assertions on parsed fields. A pattern match over the body can pick up the wrong six digits.
extracted.codesholds the code itself. - An eye on the inbox limit. Inboxes count toward the plan: 2 on Free, 5 on Developer, 50 on Startup. Past the limit, creating one answers
403 inbox_limit_reached.
To test how your own agent handles an attack, run a drill: POST /v1/guard/drill sends realistic test mail through the real pipeline into one of your own inboxes.
Questions
How do I test an email verification flow end to end?
Create an inbox for the run, sign up with its address, wait for the message, and assert on the parsed code or link. The wait returns the next delivered message, or times out after up to 60 seconds.
Why use a fresh inbox for each test run?
A shared inbox lets parallel runs read each other's messages and lets an old code satisfy a new test. A fresh inbox per run, with the wait starting at its creation time, removes both.
Can a QA agent test email flows through MCP?
Yes. The MCP server has create_inbox and wait_for_message tools, with the same filters as the REST call. Results are the safe view.
How many test inboxes can I create?
Inboxes count toward the plan: 2 on Free, 5 on Developer and 50 on Startup. Past the limit, creating one answers 403 inbox_limit_reached.