Integrating Temp Mail into Tests and CI

The Mail.td REST API is designed for end-to-end testing — verifying signups, password resets, and email-triggered workflows behave correctly. This guide focuses on integration patterns for common test tools.

For the raw endpoint reference (request/response shapes), see the API page or docs.mail.td.

Selenium / Playwright / Cypress

The pattern: create a fresh inbox before each test, sign up your app using that address, then poll the API for the verification email.

// Pseudocode — adapts to any test framework
async function signUpFlow(page) {
  // 1. Create temp mailbox
  const mailbox = await fetch("https://api.mail.td/api/accounts", {
    method: "POST",
    headers: {
      Authorization: "Bearer td_xxx",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      address: `test-${Date.now()}@mail.td`,
      password: "secret"
    })
  }).then(r => r.json());

  // 2. Sign up your app with mailbox.address
  await page.goto("/signup");
  await page.fill("[name=email]", mailbox.address);
  await page.click("button[type=submit]");

  // 3. Poll for the verification email (up to 30s)
  for (let i = 0; i < 30; i++) {
    const list = await fetch(
      `https://api.mail.td/api/accounts/${mailbox.id}/messages`,
      { headers: { Authorization: "Bearer td_xxx" } }
    ).then(r => r.json());
    if (list.messages.length > 0) {
      // List response has no body — fetch the message detail to get text_body
      const msg = await fetch(
        `https://api.mail.td/api/accounts/${mailbox.id}/messages/${list.messages[0].id}`,
        { headers: { Authorization: "Bearer td_xxx" } }
      ).then(r => r.json());
      const link = extractLink(msg.text_body);
      await page.goto(link);
      break;
    }
    await new Promise(r => setTimeout(r, 1000));
  }
}

CI/CD pipelines

For GitHub Actions, GitLab CI, CircleCI, or any pipeline:

• Store one API token as a CI secret (rotate it from the dashboard if it leaks)
• Each test job creates its own mailbox — avoids race conditions across parallel jobs
• Use a unique address per test (e.g. test-${RUN_ID}-${TEST_ID}@mail.td) so failures are easier to debug
• Tear down nothing — mailboxes auto-expire, no cleanup script needed

Webhooks for faster pipelines (Pro)

Polling adds latency to every test. For long-running test suites, register a webhook URL that receives a POST when new email arrives. Your test waits on the webhook delivery instead of polling 30 times. Cuts a typical 5–15 second wait to under 1 second.

Webhooks are HMAC-SHA256 signed — verify the signature header before processing.

SDK install

npm install mailtd       # Node.js / TypeScript
pip install mailtd       # Python
go get github.com/mailtd/mailtd-go    # Go

For full endpoint reference, see mail.td/api.