Temp Mail API for Playwright

Why Playwright tests need real inboxes

Mocking email is fast, but it misses the integration risk: the template can change, the queue can delay, the verification link can be malformed, or the OTP can be hidden in HTML instead of text. A real disposable inbox tests the actual signup path while still keeping every run isolated.

TempMailGrab gives each Playwright run a private temporary address, keeps it alive long enough for retries, and exposes extracted_otp and extracted_links so your test does not scrape MIME.

Recommended flow

1. Create an inbox in test setup with POST /api/v1/inbox.
2. Fill your app's signup form with the returned address.
3. Poll GET /api/v1/inbox/:id/messages until the OTP or verification link appears.
4. Complete the Playwright assertion with the parsed field.
5. Delete the inbox in teardown, or let the TTL expire automatically.

Playwright fixture shape

import { test as base, expect } from "@playwright/test";
import { TempMailGrab } from "tempmailgrab";

export const test = base.extend({
  inbox: async ({}, use) => {
    const tmg = new TempMailGrab({ apiKey: process.env.TMG_API_KEY });
    const inbox = await tmg.createInbox({ ttlSeconds: 3600 });
    await use(inbox);
    await inbox.delete().catch(() => {});
  },
});

test("user can verify email", async ({ page, inbox }) => {
  await page.goto("https://your-app.example/signup");
  await page.getByLabel("Email").fill(inbox.address);
  await page.getByRole("button", { name: "Create account" }).click();

  const otp = await inbox.waitForOtp({ timeoutMs: 60000 });
  await page.getByLabel("Verification code").fill(otp);
  await page.getByRole("button", { name: "Verify" }).click();

  await expect(page.getByText("Account verified")).toBeVisible();
});

Parallel test safety

Do not share one disposable address across a Playwright project. Create the inbox inside the fixture so each worker receives a separate address. That prevents one test from reading another test's OTP and turns email delivery into an isolated dependency instead of global state.

Useful companion links

• Full API documentation
• OpenAPI specification
• Email testing API overview
• Long-form Playwright tutorial
• JavaScript SDK source

Last verified: August 2026. Endpoint examples and package versions may change; check the API docs before copying into production CI.