TempMaily.co
Menu
For developers & QA

Temp mail API

Create disposable email inboxes and read verification mail from code. Nine REST endpoints, signed webhooks, an OpenAPI spec, and one flat price — no enterprise tier between your test suite and an API key. Full reference in the docs.

The whole loop in four calls

Every endpoint authenticates with an xtm_ Bearer key against {origin}/api/v1. Create, use, read, delete — the receive-side loop behind signup codes, magic links, and password resets:

REST quickstart
# 1 · Create a fresh inbox for this test run
curl -X POST https://tempmaily.co/api/v1/inboxes \
  -H "Authorization: Bearer $XTM_KEY"
# → { "id": "ibx_…", "address": "k7f2q9@…" }

# 2 · Use the address in your signup flow, then poll
curl https://tempmaily.co/api/v1/inboxes/<id>/messages \
  -H "Authorization: Bearer $XTM_KEY"

# 3 · Read the body and extract the code
curl https://tempmaily.co/api/v1/messages/<messageId> \
  -H "Authorization: Bearer $XTM_KEY"

# 4 · Tear down so parallel runs never collide
curl -X DELETE https://tempmaily.co/api/v1/inboxes/<id> \
  -H "Authorization: Bearer $XTM_KEY"

Built for test suites

The pattern that keeps email E2E tests green is one fresh inbox per test: no shared state, no cross-run collisions, nothing to reset between retries. In a Playwright test it looks like this:

Playwright example
// One inbox per test — the pattern that keeps suites green
const inbox = await api.post("/inboxes");

await page.fill("#email", inbox.address);
await page.click("#signup");

// Poll with a deadline, never a fixed sleep
const message = await pollUntil(
  () => api.get(`/inboxes/${inbox.id}/messages`),
  { until: (m) => m.length > 0, timeoutMs: 30_000 },
);

const body = await api.get(`/messages/${message[0].id}`);
const code = body.bodyText.match(/code is (\d{6})/)?.[1];

await page.fill("#otp", code);
await api.delete(`/inboxes/${inbox.id}`);

Deeper recipes: Playwright email verification, Cypress email testing, and running the loop in CI.

Nine endpoints, no surprises

POST
/inboxes
Create a disposable inbox
GET
/inboxes
List your inboxes
DELETE
/inboxes/{id}
Delete an inbox
GET
/inboxes/{id}/messages
List messages
GET
/messages/{id}
Read a full message
DELETE
/messages/{id}
Delete a message
POST
/webhooks
Register a signed webhook
GET
/webhooks
List webhooks
DELETE
/webhooks
Remove a webhook

Webhooks are signed, so your receiver can verify the payload came from us. Prefer push over polling for long-running workflows; in tests, polling with a deadline is simpler and plenty fast.

Honest constraints

Agents speak MCP, same key

The same inboxes are exposed as MCP tools for Claude Desktop, Claude Code, Cursor, and any MCP-capable agent framework — one config block and the agent can mint and read inboxes itself. That story lives on email for AI agents.

Get a key

$9.90/month or $90/year, flat: REST API, signed webhooks, MCP server, up to 10 concurrent addresses, 2GB storage, custom domains. Compare everything on the pricing page.

Go Premium

Custom domain, up to 10 addresses, 2GB storage, no ads — from $7.50/mo billed yearly.

View plans

Temp mail API FAQ

Is there a free temp mail API?

TempMaily's free tier is the anonymous browser inbox on the homepage — great for trying the product by hand, but it has no programmatic access. The API is part of Premium: one flat plan at $9.90 per month or $90 per year that includes the REST API, signed webhooks, the MCP server, up to 10 concurrent addresses, and custom domains. There is deliberately no separate enterprise tier for API access.

How do I get an API key?

Subscribe to Premium, open the dashboard's API Keys section, and create a key. Keys are prefixed xtm_ and authenticate every endpoint as a standard Bearer token in the Authorization header. The same key works for the REST API and the MCP server, so you can prototype in an agent client and ship the same flow as HTTP calls without new credentials.

Can my tests receive mail on our own domain?

Yes. Premium includes custom domains: delegate a domain you own, and MX plus SPF records are configured automatically. API-created inboxes can then receive at addresses on that domain, which matters for staging environments that reject known disposable domains — your domain is not on any blocklist because it is yours alone.

Should I poll for messages or use webhooks?

Poll in tests, push in workflows. A test that just triggered a signup should poll the inbox with a deadline — it is simple, self-contained, and the message arrives within seconds. Webhooks fit long-running systems: register an endpoint once and TempMaily calls it on delivery, with a signature you can verify, so nothing sits in a polling loop. Both are included; neither costs extra.

Can I send email through the API?

No — inboxes are receive-only, by design. Outbound throwaway mail is a spam vector that gets a service's entire domain pool blocklisted, which would break receiving for everyone. If your test needs to inspect mail your own application sends, the right tool is an outbound sandbox like Mailtrap or Mailpit; our email testing tools guide covers when each direction applies.

Is there an OpenAPI spec or SDK?

The full OpenAPI 3 spec is published at /openapi.json — generate a typed client for any language with your usual toolchain (openapi-typescript, openapi-generator, and similar all work). The surface is small enough that many teams just use fetch or curl: nine endpoints covering inboxes, messages, and webhooks. Working Cypress and Playwright recipes live in the docs and blog.

What are the limits?

Premium includes up to 10 concurrent addresses per account, standard rate limits sized for test suites and agent workloads, and 2GB of message storage. Inboxes you create through the API persist until you delete them — they are not on the free tier's 24-hour timer — so clean up in your test teardown, or list and prune stale inboxes at suite start.