Tempboxy
Developer API · 7 min read

Automating signup & OTP tests with a free temp mail API.

Automate signup verification, password resets, and OTP extraction in Playwright, Node.js, and Python using Tempboxy free disposable email REST API.

Why shared test inboxes make E2E suites flaky

End-to-end tests for authentication flows — account registration, email verification, magic links, and password resets — are notoriously brittle when teams reuse a single static Gmail or catch-all mailbox. Parallel CI workers race against one another, pull stale OTP codes from previous runs, or hit rate limits on the same address.

Provisioning a brand-new mailbox per test case through a free temp mail API guarantees complete isolation. Each Playwright or pytest run receives a unique address on a live standard (.com) or academic (.edu.pl) domain and reads only the messages sent to that specific test execution.

The 4-step disposable email API lifecycle

Tempboxy exposes a zero-friction JSON REST interface at /api/v1 requiring no OAuth dance or credit card:

  1. Discover live domains: GET /api/v1/domains returns currently active domains across both upstream providers.
  2. Provision an isolated inbox: POST /api/v1/inboxes with {"provider": "tempmail", "ttl": "10m"} returns a unique address and signed inbox_id.
  3. Poll for code or full messages: GET /api/v1/inboxes/:id/code returns the newest extracted OTP and confirmation link, while /messages returns full HTML, plain text, normalized attachments, and tracker security scores.
  4. Burn on teardown: DELETE /api/v1/inboxes/:id removes the temporary address cleanly once the test passes.

Complete Playwright OTP test example

Using Playwright's native expect.poll helper avoids brittle hard-coded waitForTimeout sleeps and retries cleanly until SMTP delivery completes:

tests/signup-otp.spec.ts
import { test, expect } from '@playwright/test';

const API = 'https://tempboxy.com/api/v1';

test('new user completes email OTP verification', async ({ page, request }) => {
  const createRes = await request.post(`${API}/inboxes`, {
    data: { provider: 'tempmail', ttl: '10m' },
  });
  expect(createRes.status()).toBe(201);
  const { address, inbox_id } = await createRes.json();

  try {
    await page.goto('/signup');
    await page.getByLabel('Email').fill(address);
    await page.getByRole('button', { name: 'Continue' }).click();

    let otpCode = null;
    await expect.poll(async () => {
      const pollRes = await request.get(`${API}/inboxes/${inbox_id}/code`);
      const payload = await pollRes.json();
      otpCode = payload.code;
      return otpCode;
    }, { timeout: 30000, intervals: [2000, 3000, 4000] }).toMatch(/^\d{4,8}$/);

    await page.getByLabel('Verification code').fill(otpCode);
    await page.getByRole('button', { name: 'Verify' }).click();
    await expect(page).toHaveURL(/dashboard/);
  } finally {
    await request.delete(`${API}/inboxes/${inbox_id}`);
  }
});

Python requests & pytest helper

For backend integration tests in Python, a tiny polling helper handles both numeric OTPs and password-reset URLs across either provider pool:

email_helper.py
import time
import requests

API = "https://tempboxy.com/api/v1"

def wait_for_verification(inbox_id: str, timeout_s: int = 30) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        res = requests.get(f"{API}/inboxes/{inbox_id}/code", timeout=10).json()
        if res.get("code") or res.get("verification_link"):
            return res
        time.sleep(3)
    raise TimeoutError("Timed out waiting for verification email")

Auditing HTML templates, attachments & trackers

Beyond checking that an email arrived, engineering teams often need to inspect transactional templates visually before release. Every message returned by GET /api/v1/inboxes/:id/messages includes a security object reporting accidental 1x1 tracking pixels, UTM parameters, and spam-risk score alongside normalized attachments.

For manual visual QA, open the developer email testing inbox to inspect real incoming emails at full desktop width or 375px mobile width, inspect raw HTML markup, and download RFC-5322 .eml archives for bug reports. You can also test deliverability DNS records beforehand using the Email Domain MX Checker.

Best practices for TTL and cleanup in CI

  • Use short TTLs in CI: Pass "ttl": "10m" for ephemeral test runs so unused recovery tokens expire promptly.
  • Always delete in a finally block: Calling DELETE /api/v1/inboxes/:id frees temporary mailboxes immediately.
  • Poll responsibly: Back off to 3–4 second intervals rather than tight loops; SMTP handshakes rarely complete in under 2 seconds.

Key Takeaway

A free temp mail API lets automated test suites provision a fresh disposable email address per CI run, trigger real signup or password-reset emails, and poll a JSON endpoint for the extracted OTP code or verification link. This eliminates shared test inbox collisions without paying for per-seat QA email platforms.

Continue reading

Related engineering guides

Questions

Frequently asked

Does the Tempboxy API require an API key or account signup?

No. All /api/v1 endpoints work directly over JSON HTTP with polite IP-based fair-use rate limiting and zero account creation.

Can I choose between .com and .edu.pl domains via the API?

Yes. Pass "provider": "tempmail" for standard .com domains or "provider": "edumail" for .edu.pl domains in POST /api/v1/inboxes.

Can I restore an inbox created via API inside the web UI?

Yes. Every API response includes a signed recovery_token (tbx_v1_...) that you can paste into /reusable-temp-mail to inspect messages visually.

Need more answers? Browse all 29 topics in the Complete Tempboxy FAQ.