# Test email flows with an AI agent and a real inbox

> How to test sign-up and verification emails end to end: a fresh inbox per run, a wait for the message, and the code and link parsed for the assertion.

Source: https://trotta.email/use-cases/testing-email-flows

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 November 20, 2026

## 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.

1. Create an inbox for the run. A `clientId` makes creation idempotent, so a retry of the same run gets the same inbox.
2. Run the flow under test with the inbox address.
3. Wait for a message with a code, starting from the moment the inbox was created.
4. Assert on `extracted.codes` and `extracted.verify_links`, which are filled in on arrival.

```typescript
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](https://trotta.email/docs/concepts) 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](https://trotta.email/learn/spf-dkim-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.** `after` takes 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 `from` or `subject` to the wait, or `hasCode` for the message with the code.
- **Assertions on parsed fields.** A pattern match over the body can pick up the wrong six digits. `extracted.codes` holds 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`.

## Related

- [Use cases](https://trotta.email/use-cases)
- [Email testing with real inboxes](https://trotta.email/learn/email-testing-with-real-inboxes) Guides
- [Verification codes for AI agents](https://trotta.email/learn/verification-codes-for-ai-agents) Guides
- [Prompt injection by email](https://trotta.email/threats/prompt-injection-by-email) Threat library
- [SDKs and CLI](https://trotta.email/docs/sdks) Docs
- [TypeScript](https://trotta.email/integrations/typescript) Integrations

Give your agent an inbox of its own. Free for two inboxes. No card.

[Get an inbox](https://trotta.email/signup) [See every use case](https://trotta.email/use-cases)
