# Email testing with real inboxes: an end-to-end guide

> Test sign-up, password reset and notification emails end to end: a real inbox per test run, a wait call instead of sleeps, and a worked Playwright example.

Source: https://trotta.email/learn/email-testing-with-real-inboxes

To test an email flow end to end, give each test run a real inbox of its own, trigger the flow with that address, wait for the message, then assert on its code, link and content. A fresh inbox per run keeps parallel tests from reading each other's mail, and a blocking wait call replaces fixed sleeps.

Updated November 20, 2026

## Why test email with a real inbox?

A real inbox tests what a mock cannot: that the email was sent, to the right address, with a link that works. A mocked mailer proves your code called a function. A real inbox proves a message crossed the network and arrived with a working code inside.

| Approach | What it proves | What it misses |
| --- | --- | --- |
| Mock the mailer | Your code asked to send | Templates, links and delivery |
| A local mail catcher | The message was built and handed over | Real delivery, and everything outside your machine |
| One shared test mailbox | Real delivery | Isolation: parallel runs read each other's mail |
| A real inbox per test run | Real delivery, and each run sees its own mail alone | How other mailbox providers would file the message |

The last row is the pattern this guide builds. Its blind spot is worth stating: a message arriving in a test inbox says nothing about whether another provider would put it in a spam folder.

## What is the pattern for testing with a real inbox?

Testing with a real inbox follows six steps, and the same six work for sign-up, password reset and notification emails.

1. Create an inbox for the run, through an API, before the test starts.
2. Note the time, then trigger the flow in your app with that inbox's address.
3. Wait for the message with a call that blocks until it arrives.
4. Assert on what matters: the sender, the subject, the code or the link.
5. Follow the link or submit the code, and assert on your app's state.
6. Delete the inbox when the run ends.

Fixed sleeps are a common cause of slow, flaky email tests. Too short and the test fails. Too long and the suite crawls. A wait call returns the moment the message lands, and fails clearly on a timeout.

## How does a sign-up test look in Playwright?

A sign-up test in Playwright creates an inbox, fills the form with its address, waits for the confirmation email and opens the link. This one uses a Trotta Mail inbox. Install the SDK with `npm install trotta-mail` and put an API key in `TROTTA_MAIL_API_KEY`. The key needs the `admin` scope, because it creates and deletes inboxes.

`signup.spec.ts`:

```typescript
import { test, expect } from "@playwright/test";
import { TrottaMail } from "trotta-mail";

const mail = new TrottaMail({ apiKey: process.env.TROTTA_MAIL_API_KEY });

test("sign-up sends a confirmation link that works", async ({ page }, testInfo) => {
  // A fresh inbox for this attempt. clientId makes the create call safe to repeat.
  const runId = `${Date.now()}-${testInfo.workerIndex}`;
  const inbox = await mail.inboxes.create({ name: `run-${runId}`, clientId: `run-${runId}` });
  const since = new Date();

  try {
    await page.goto("https://staging.trotta.io/signup");
    await page.getByLabel("Email").fill(inbox.address);
    await page.getByLabel("Password").fill("correct-horse-battery-staple");
    await page.getByRole("button", { name: "Create account" }).click();

    // Blocks until the message is delivered. No sleeps.
    const msg = await mail.inboxes.wait(inbox.id, { from: "trotta.io", after: since, timeout: 60 });
    if (!msg) throw new Error("No confirmation email within 60 seconds");
    expect(msg.subject).toContain("Confirm");

    const link = msg.extracted.verify_links[0];
    expect(new URL(link).hostname).toBe("staging.trotta.io");

    await page.goto(link);
    await expect(page.getByText("Your email is confirmed")).toBeVisible();
  } finally {
    await mail.inboxes.delete(inbox.id);
  }
});
```

Three lines carry the weight. The `after` time means the test never matches mail from an earlier attempt, and never misses a message that landed before the wait began. The `from` filter ignores anything else sent to the address. The hostname check fails the test if the email points at production by mistake.

## How do you test a one-time code or a password reset?

A one-time code or a password reset is tested with the same six steps and a different assertion. For a code, wait with `hasCode` and read `extracted.codes`:

```typescript
const msg = await mail.inboxes.wait(inbox.id, { hasCode: true, after: since, timeout: 60 });
if (!msg) throw new Error("No code within 60 seconds");

await page.getByLabel("Verification code").fill(msg.extracted.codes[0].value);
```

For a reset, any language works over plain HTTP. This pytest test asks for a reset and picks the link by its domain. Every link in a message is listed in `links` with its `url` and `domain`, and `auth_kind` says what kind of login mail arrived.

`test_password_reset.py`:

```python
import os
import uuid
from datetime import datetime, timezone

import requests

API = "https://api.trotta.email/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['TROTTA_MAIL_API_KEY']}"}

def test_password_reset_sends_a_working_link():
    run_id = uuid.uuid4().hex[:8]
    inbox = requests.post(
        f"{API}/inboxes",
        json={"name": f"run-{run_id}", "client_id": f"run-{run_id}"},
        headers=HEADERS,
        timeout=30,
    ).json()
    try:
        since = datetime.now(timezone.utc).isoformat()
        request_password_reset(inbox["address"])  # the flow under test

        waited = requests.get(
            f"{API}/inboxes/{inbox['id']}/wait",
            params={"subject": "reset", "after": since, "timeout": 60},
            headers=HEADERS,
            timeout=70,
        ).json()
        message = waited["message"]
        assert message is not None, "no reset email within 60 seconds"
        assert message["auth_kind"] == "reset"

        link = next(item["url"] for item in message["links"] if item["domain"] == "staging.trotta.io")
        assert requests.get(link, timeout=30).status_code == 200
    finally:
        requests.delete(f"{API}/inboxes/{inbox['id']}", headers=HEADERS, timeout=30)
```

Then test what a mailbox cannot show: the reset link works once, and an old link stops working when a new one is requested.

For a notification, assert on `from`, `subject` and `text`. A key reads the safe view, which is the visible text of the message. To assert on the original HTML, ask for `view=full` with a key that holds the `mail:full` scope. Keep that key in your test secrets, and never give one to an agent.

## Should each test get its own inbox?

Each parallel worker needs its own inbox at least, and a fresh inbox per run is the cleanest form. The aim is that no test can read mail meant for another.

| Setup | Isolation | Inboxes used | Fits |
| --- | --- | --- | --- |
| One inbox per run, deleted after | Complete | One per test in flight | Small suites, strict isolation |
| One inbox per worker, kept | By the `after` time and the sender | One per worker | Large suites on a small plan |
| One inbox for everything | None | One | A single serial test |

With one inbox per worker, the `after` filter does the isolating: each test waits for mail that arrived after it started.

## What limits apply to test inboxes in Trotta Mail?

Test inboxes in Trotta Mail count toward the plan like any inbox: 2 on Free, 5 on Developer, 50 on Startup. Each email received counts toward the month's emails: 1,000 on Free, 5,000 on Developer, 50,000 on Startup. Size your parallel workers to the plan.

- Test addresses are at `trotta.email` on every plan. Addresses on your own domain need a paid plan.
- Use an agent inbox, the default kind. In a human's mailbox, login mail is sealed from every key, so a test would never see the code.
- The inbox screens test mail before it is delivered, like any mail. A wait never returns held mail, so when a test times out, look at the inbox's `counts.held` before blaming your app.
- A key without the `guard:release` scope cannot delete an inbox that holds mail the guard stopped, or one set stricter than the default. A human reviews held mail in the web app.
- `POST /v1/guard/drill` with scenario `otp` sends a realistic code email through the real pipeline into your own inbox, to show what one looks like in the API.

The screening gives a test one more thing to assert on. Every message carries a verdict, and `verdict.auth` holds the SPF, DKIM and DMARC results for the mail your app sent. A test that expects `pass` catches a sending domain that lost its setup. See the [testing use case](https://trotta.email/use-cases/testing-email-flows), or the [API reference](https://trotta.email/docs/api) for every field on a message.

## Questions

### How do I stop email tests from being flaky?

Replace fixed sleeps with a wait call that blocks until the message arrives. Filter by sender and by the time the test started, and fail with a clear message on a timeout.

### Can I run email tests with real inboxes in CI?

Yes. The test makes outbound HTTPS calls with an API key kept as a CI secret, and nothing has to listen for inbound connections.

### Does a real test inbox show whether my email lands in spam at Gmail or Outlook?

No. It proves the message was sent and that its content works. Where another mailbox provider files it depends on that provider's filters and needs its own check.

### Is a disposable inbox the same as a real inbox?

A disposable inbox for testing is a real inbox with a short life: it receives mail over the internet like any other. What matters is that it is private to your account and created through an API.

### Can I test with addresses on my own domain?

Yes, on a paid plan. Connect the domain, then pass `domain` when you create the inbox.

## Related

- [API reference](https://trotta.email/docs/api) Docs
- [Testing email flows](https://trotta.email/use-cases/testing-email-flows) Use cases
- [SDKs and CLI](https://trotta.email/docs/sdks) Docs
- [TypeScript](https://trotta.email/integrations/typescript) Integrations
- [How an AI agent receives a verification code by email](https://trotta.email/learn/verification-codes-for-ai-agents) Guides
- [Email webhooks vs polling: four ways an agent learns that mail arrived](https://trotta.email/learn/email-webhooks-vs-polling) Guides

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

[Get an inbox](https://trotta.email/signup) [Read the docs](https://trotta.email/docs)
