Test email flows in Playwright with a real temporary inbox

Test flow

1. Create an inbox through the Inboxes.Run REST API.
2. Fill box.address into the application under test.
3. Submit the signup, password-reset or verification form.
4. Poll /mailboxes/{id}/messages.
5. Assert the expected subject, token, link or marker, then continue the browser test.

Minimal Playwright example

import { test, expect } from "@playwright/test";

const API = "https://inboxes.run/api/v1";
const key = process.env.INBOXESRUN_API_KEY;

async function inbox(path, options = {}) {
  const response = await fetch(API + path, {
    ...options,
    headers: {
      Authorization: `Bearer ${key}`,
      "Content-Type": "application/json",
      ...(options.headers || {}),
    },
  });
  if (!response.ok) throw new Error(`Inbox API: ${response.status}`);
  return response.json();
}

test("signup sends email", async ({ page }) => {
  const box = await inbox("/mailboxes", { method: "POST", body: "{}" });

  await page.goto("https://your-app.example/signup");
  await page.getByLabel("Email").fill(box.address);
  await page.getByRole("button", { name: /sign up/i }).click();

  let received = false;
  for (let i = 0; i < 20; i++) {
    const messages = await inbox(`/mailboxes/${box.id}/messages`);
    if (JSON.stringify(messages).includes("Welcome")) {
      received = true;
      break;
    }
    await new Promise(r => setTimeout(r, 3000));
  }

  expect(received).toBeTruthy();
});

Why use a public inbox instead of a local mail catcher?

MailHog, Mailpit and similar tools are useful when your application sends into a local test SMTP server. A public temporary inbox is useful when the system under test sends through its real external mail path and your E2E test needs to observe what actually arrives.

Keep the test deterministic

Create a new mailbox per test or test worker. Store the API key in your secret manager, never in the repository. Temporary inboxes are receive-only and are intended for short-lived testing and automation workflows.

Try it

Open a temporary inbox in the browser for free. For programmatic use, sign in and open API / IMAP to generate an API key and see the current limits.

Open Inboxes.Run · API / IMAP