← Back to blog
· Updated ·7 min read

Temp Mail for Developers: Testing Email Flows

Test sign-up, OTP and password-reset emails end to end with a temporary inbox API: endpoints, isolation, polling, webhooks, rate limits and flaky-test fixes.

Why Email Is the Hardest Part of an End-to-End Test

Most user journeys that matter touch email: sign-up confirmation, one-time login codes, password resets, invitations, order receipts. These flows are also the ones most likely to break silently. A template change removes the link, a provider rejects mail from a new sending domain, or a queue backs up and messages arrive a minute late.

Unit tests cannot catch that, because the bug lives between your application, your email provider and a real receiving mail server. To test the whole path you need an address that can genuinely receive mail, plus a way for your test code to read it. That is exactly what a temporary inbox API provides.

This guide explains how to wire InboxBurn into automated tests, and the practices that keep those tests reliable.

The Building Blocks

The full reference lives in the API docs; these are the endpoints you will use most:

  • GET /api/generate creates an address on a random active domain and returns address, domain, token and expires_at. An optional ?expiry= query parameter sets the lifetime in milliseconds, from 10 minutes up to 7 days; the default is 24 hours.
  • POST /api/generate/custom with a JSON body { "prefix": "...", "domain": "...", "expiry": ... } claims a specific address. It returns 409 if that address is already active.
  • GET /api/domains lists the domains you can use for custom addresses.
  • GET /api/inbox/{address} lists received messages (id, sender, subject, received time). Send the inbox token in the X-Inbox-Token header.
  • GET /api/email/{id}?address={address} returns one message with body_text, body_html and attachment metadata.
  • POST /api/inbox/{address}/extend adds 24 hours to a running inbox.
  • DELETE /api/inbox/{address} removes the messages in an inbox.

Two credentials are involved, and they do different things. The inbox token proves you may read one specific inbox; keep it out of URLs and logs. An API key, sent as Authorization: Bearer ib_live_..., identifies your account, applies your plan's quota and lets you attach inboxes to your account. Plan details are on the pricing page.

A Minimal Polling Helper

The simplest integration creates an inbox, triggers your app, and polls until a matching message arrives. This sketch uses plain fetch in Node 18 or later:

js
const BASE = 'https://api.inboxburn.com';
const headers = { Authorization: `Bearer ${process.env.INBOXBURN_KEY}` };

export async function createInbox() {
  const res = await fetch(`${BASE}/api/generate?expiry=3600000`, { headers });
  if (!res.ok) throw new Error(`generate failed: ${res.status}`);
  return res.json(); // { address, token, expires_at, ... }
}

export async function waitForEmail({ address, token }, match, timeoutMs = 90000) {
  const deadline = Date.now() + timeoutMs;
  let delay = 3000;
  while (Date.now() < deadline) {
    const res = await fetch(`${BASE}/api/inbox/${address}`, {
      headers: { 'X-Inbox-Token': token },
    });
    if (res.ok) {
      const { emails } = await res.json();
      const hit = emails.find(match);
      if (hit) {
        const full = await fetch(`${BASE}/api/email/${hit.id}?address=${address}`, {
          headers: { 'X-Inbox-Token': token },
        });
        return full.json();
      }
    }
    await new Promise((r) => setTimeout(r, delay));
    delay = Math.min(delay * 1.5, 10000);
  }
  throw new Error(`No matching email for ${address} within ${timeoutMs} ms`);
}

A test then reads naturally:

js
const inbox = await createInbox();
await page.fill('#email', inbox.address);
await page.click('button[type=submit]');
const mail = await waitForEmail(inbox, (m) => /verify/i.test(m.subject));
const code = mail.body_text.match(/\b(\d{6})\b/)?.[1];

Framework-specific recipes are in the Playwright guide and the Cypress guide.

Respect the Rate Limits

Anonymous requests are limited per IP. According to the docs, GET /api/generate allows 10 requests per minute and GET /api/inbox/{address} allows 20 per minute. Exceeding a limit returns HTTP 429, and repeated abuse can trigger a temporary block.

That shapes how you poll:

  • Poll every few seconds, not in a tight loop. The backoff in the helper above starts at 3 seconds and caps at 10.
  • A parallel suite of 30 workers each creating inboxes will hit the generate limit quickly. Use an API key, create inboxes lazily only where a test truly needs mail, or reuse one inbox per worker with unique subjects.
  • Treat 429 as a signal to slow down rather than an immediate failure.

Isolation: Never Let Tests See Each Other's Mail

Flaky email tests are almost always isolation problems. Two tests share an address, one picks up the other's message, and the failure is impossible to reproduce.

  • One inbox per scenario. Random addresses from /api/generate are naturally isolated.
  • Deterministic custom prefixes help when you need to find mail later. Include the CI run ID and test name, for example ci-4821-signup, so every run is unique and failures are traceable. Do not reuse a fixed prefix across runs: once it expires anyone can claim it, and a 409 response tells you it is still active.
  • Match precisely. Filter by sender and subject, and if possible embed a unique token (such as the test's run ID) in the user's name so you can confirm the message belongs to this test.
  • Ignore older messages. Record the time before triggering the email and ignore anything received earlier.

Timeouts That Reflect Reality

Email is not instant. Your provider queues messages, receiving servers may defer first attempts, and spam checks take time. Most messages arrive within seconds, but a sensible test timeout is 60 to 120 seconds, with a clear error message on failure. If timeouts happen regularly, read why verification emails arrive late before raising the limit further; the root cause is often on the sending side.

Parse Codes and Links Robustly

  • Prefer `body_text` for codes. HTML bodies wrap digits in spans and tables that break naive regular expressions.
  • Anchor your patterns. A bare \d{6} also matches dates, order numbers and postal codes. Look for the code near a label like "your code is", or ask your team to place codes in a predictable element.
  • For links, parse the HTML and select the anchor by its text or a data attribute rather than taking the first URL, which is often a logo or tracking link.
  • Decode HTML entities such as &amp; before following a link, or query parameters will be wrong.

Webhooks Instead of Polling

For high-volume suites or automation, polling wastes requests. On plans that include them, signed webhooks send an email.received event to your endpoint when mail arrives at an inbox created with your API key. Each request carries a timestamp and an HMAC-SHA256 signature; verify both before trusting the payload, as shown in the docs. Webhooks also connect inboxes to no-code tools, covered in Zapier and Make email webhooks.

Hygiene and Safety

  • Never send test mail to real customers. Seed test users only with addresses you generated. A staging environment pointed at production data is how real people receive "test" emails.
  • Clean up. Call DELETE /api/inbox/{address} at the end of a test that received sensitive fixtures. Inboxes also expire on their own, but remember that expired content is archived by the service rather than instantly erased, so do not route real personal data through test inboxes.
  • Keep tokens secret. Store API keys in your CI secret store, and avoid printing inbox tokens in logs or test reports.
  • Use short lifetimes. Request an expiry that matches the test, such as one hour, instead of the 24-hour default.
  • Test sender health separately. A delivered message can still land in spam at a real provider. The spam checker and email DNS checker help check content and SPF, DKIM and DMARC records.

Where to Go Next

Start with the QA email testing API overview, then copy the helper above into your test utilities and wire it into one critical flow, usually sign-up. Once that is stable, add password reset and invitations. Email bugs that used to reach production will start failing in CI instead, where they belong.