Email Testing API

The problem with testing email flows

Almost every product has a flow that only works if an email actually arrives: sign-up confirmation, password reset, magic link, two-factor code, invitation acceptance. These are the flows most likely to break in production and the least likely to be covered by an automated test — because testing them properly is awkward.

The usual workarounds share one failure mode. A shared QA mailbox makes parallel runs compete for messages: test A's confirmation email gets claimed by test B, the wrong code is submitted, and the failure is non-deterministic. Mocking the mail transport tests your code but not your templates, your ESP configuration, or deliverability — the parts that actually break. Reading a real inbox over IMAP means credentials in CI, connection limits, and a mailbox that fills up and needs cleaning.

An email testing API removes the shared resource. Each test creates its own inbox, uses it, and lets it expire. There is nothing to reset between runs and nothing to contend over.

How it works

1. Create an inbox. POST /api/v1/inbox returns a real, working address in milliseconds.
2. Poll for the message. GET /api/v1/inbox/{id}/messages returns messages newest-first, each already carrying extracted_otp and extracted_links.
3. Or subscribe. Register a webhook and the parsed message is POSTed to you instead, signed with HMAC-SHA256.

The code and the verification links are extracted at ingestion, on the server, before you ever see the message. That removes the most fragile part of an email test: you are not maintaining a regex over an HTML body that breaks the next time someone edits the template.

Create an inbox

curl -X POST https://tempmailgrab.com/api/v1/inbox \
  -H "Authorization: Bearer $TMG_API_KEY" \
  -H "content-type: application/json" \
  -d '{"prefix":"ci-run-8412","ttl_seconds":3600}'

# -> {
#      "id": "8f14e45f-ceea-467a-9f0b-2c1d0d5e7a11",
#      "address": "ci-run-8412@tempmailgrab.com",
#      "created_at": 1787834622,
#      "expires_at": 1787838222
#    }

prefix and ttl_seconds are both optional. Omit the prefix and you get a random 12-character local part; omit the TTL and the inbox lives 24 hours. TTL accepts 600–259200 seconds (10 minutes to 72 hours), so a CI inbox can be scoped to the length of the job that owns it.

Read the message and the code

curl https://tempmailgrab.com/api/v1/inbox/$INBOX_ID/messages \
  -H "Authorization: Bearer $TMG_API_KEY"

# -> {
#      "address": "ci-run-8412@tempmailgrab.com",
#      "messages": [{
#        "id": "aa09e0aa-1359-4fb8-a801-e1b9bc02424f",
#        "sender": "no-reply@yourapp.com",
#        "subject": "Your verification code",
#        "snippet": "Your code is 448213 ...",
#        "extracted_otp": "448213",
#        "created_at": 1787834649
#      }]
#    }

Fetch a single message with GET /api/v1/inbox/{id}/messages/{messageId} for the full record: text_body, a sanitized html_body, extracted_links, raw_headers, and signed download URLs for any attachments.

Playwright

A fixture that hands each test its own address, plus a helper that waits for the code:

import { test as base, expect } from '@playwright/test';

const API = 'https://tempmailgrab.com/api/v1';
const headers = { authorization: `Bearer ${process.env.TMG_API_KEY}` };

async function waitForOtp(inboxId, timeoutMs = 30000) {
  const deadline = Date.now() + timeoutMs;
  while (Date.now() < deadline) {
    const res = await fetch(`${API}/inbox/${inboxId}/messages`, { headers });
    const { messages } = await res.json();
    const hit = messages.find((m) => m.extracted_otp);
    if (hit) return hit.extracted_otp;
    await new Promise((r) => setTimeout(r, 1000));
  }
  throw new Error('No OTP arrived within the timeout');
}

export const test = base.extend({
  inbox: async ({}, use) => {
    const res = await fetch(`${API}/inbox`, { method: 'POST', headers });
    await use(await res.json());   // inboxes expire on their own - no teardown
  },
});

test('a new user can verify their email', async ({ page, inbox }) => {
  await page.goto('/signup');
  await page.getByLabel('Email').fill(inbox.address);
  await page.getByRole('button', { name: 'Create account' }).click();

  const code = await waitForOtp(inbox.id);
  await page.getByLabel('Verification code').fill(code);
  await page.getByRole('button', { name: 'Verify' }).click();

  await expect(page.getByText('Welcome')).toBeVisible();
});

Because the fixture is per-test, Playwright's parallel workers cannot collide: worker 1 and worker 7 hold different addresses and never see each other's mail. There is no afterEach, because the inbox deletes itself.

Cypress

// cypress/support/commands.js
Cypress.Commands.add('createInbox', () =>
  cy.request({
    method: 'POST',
    url: 'https://tempmailgrab.com/api/v1/inbox',
    headers: { authorization: `Bearer ${Cypress.env('TMG_API_KEY')}` },
  }).its('body'),
);

Cypress.Commands.add('waitForOtp', (inboxId) =>
  cy.request({
    url: `https://tempmailgrab.com/api/v1/inbox/${inboxId}/messages`,
    headers: { authorization: `Bearer ${Cypress.env('TMG_API_KEY')}` },
  }).then(({ body }) => {
    const hit = body.messages.find((m) => m.extracted_otp);
    if (hit) return hit.extracted_otp;
    cy.wait(1000);
    return cy.waitForOtp(inboxId);
  }),
);

// cypress/e2e/signup.cy.js
it('verifies a new account', () => {
  cy.createInbox().then((inbox) => {
    cy.visit('/signup');
    cy.get('[name=email]').type(inbox.address);
    cy.contains('Create account').click();

    cy.waitForOtp(inbox.id).then((code) => {
      cy.get('[name=code]').type(code);
      cy.contains('Verify').click();
      cy.contains('Welcome').should('be.visible');
    });
  });
});

Webhooks instead of polling

For longer flows — a nightly job, a staging environment, an inbound-mail integration you are building — register a webhook and skip the poll loop:

curl -X POST https://tempmailgrab.com/api/v1/webhooks \
  -H "Authorization: Bearer $TMG_API_KEY" \
  -H "content-type: application/json" \
  -d '{"url":"https://your-ci.example.com/hooks/email"}'

# -> { "id": "...", "secret": "whsec_..." }

Every message to any of your inboxes is then POSTed to that URL as parsed JSON with an X-TMG-Signature header containing the HMAC-SHA256 of the body under your secret. Verify it before trusting the payload. Account-level webhooks fire for every inbox the key owns; per-inbox webhooks (POST /api/v1/inbox/{id}/webhook) scope delivery to a single address.

Testing the test harness

Wiring up email tests has a chicken-and-egg problem: until your application sends its first message you cannot tell whether your polling code works or your assertions are simply never reached. POST /api/v1/inbox/{id}/test-message injects a synthetic message — with a real, extractable code — so you can prove the harness end to end before pointing it at your app.

curl -X POST https://tempmailgrab.com/api/v1/inbox/$INBOX_ID/test-message \
  -H "Authorization: Bearer $TMG_API_KEY" \
  -H "content-type: application/json" \
  -d '{"subject":"Your code","text":"Your verification code is 448213."}'

# -> { "ok": true, "id": "...", "extracted_otp": "448213" }

Keys, limits and cost

• Authentication: Authorization: Bearer <key> or X-API-Key: <key>. Create keys in the dashboard.
• Rate limit: per key, not per IP — a CI runner behind a shared NAT gets its own budget.
• Isolation: inboxes belong to the account that created them; another key cannot read your mail.
• Cleanup: none. Inboxes and their messages are purged on expiry by a scheduled job.
• Cost: free to start — see pricing for higher limits and custom domains.

Related reading

• Temp mail API for Playwright
• Temp mail API for Cypress
• Long-form Playwright tutorial
• Long-form Cypress tutorial
• Testing email flows in your CI/CD pipeline
• How to test email verification flows
• Temp mail for QA & test automation
• Full API reference · OpenAPI spec