Temporary email API: what to check before you build on one

“Temporary email API” covers two very different kinds of product, and picking the wrong kind is the expensive mistake. One is a public disposable-mail site with an API added on. The other is a programmatic inbox service built for tests and automation. They can look the same in a feature table and behave nothing alike once your test suite or agent depends on them.

These are the questions worth answering before you build on one, whether you’re testing your own signup flow or giving an AI agent a way to receive codes.

Two kinds of temporary email API

Public disposable inboxes are built for people who don’t want to give a website their real address. On many of them, anyone who knows or guesses an inbox name can open it, and their domains are well known and widely blocked. The API, where there is one, is an afterthought.

Programmatic inbox services are built for software. Inboxes belong to whoever created them, there’s an authenticated API, messages are parsed for you, and limits are documented. Most testing and agent use cases belong here.

A quick test: if you can read an inbox without proving anything, it’s the first kind.

1. Who can read an inbox?

This question matters most, because verification emails are credentials. A sign-in code or magic link in a public inbox is a sign-in for anyone who looks. Ask:

• Is reading an inbox authenticated, and with what: an account API key, a per-inbox token, a signature?
• Can one leaked credential read every inbox, or only one?
• Do read credentials expire? Can you hand out read-only access?

Agent Temp Mail answers this with keys. Each address is derived from an Ed25519 public key, and every read is signed by the matching private key. A leaked key exposes one inbox, read links expire within 15 minutes and can’t change anything, and there’s no account-wide secret to leak.

2. How are inboxes created?

Look at what it takes to get a new address in the middle of a test or an agent run:

• A random name on a shared domain: instant, but often public.
• An API call that creates an inbox: private, but it costs a network round trip and an API key in every environment, and sometimes there’s a quota on how many inboxes you can have.
• A locally derived address: generate a keypair and you have an address, offline, with nothing to create on the server.

Creation cost decides whether you can afford a fresh inbox per test, and a fresh inbox per test is the most reliable way to stop email tests from interfering with each other.

3. What expires, and when?

Two clocks matter: how long messages are kept, and how long the address works. Short message retention is a feature, since less sensitive mail sits around, as long as it outlasts your slowest flow. Address expiry is different. When an address disappears, every account created with it loses its recovery path. For tests that rarely matters. For agents that sign up for tools they’ll use again, it does. A temporary email address that doesn’t expire goes into that trade-off.

4. How much parsing does it do?

• Is HTML converted to readable text, and are link destinations kept?
• Are codes and verification links extracted, and do you get the surrounding text or only a bare value?
• What happens to attachments and oversized messages: stored, stripped, or rejected?

Extraction with context is what makes an inbox usable by an agent. “481920” on its own is ambiguous. “Your verification code is 481920” isn’t.

5. How do you wait for mail?

Polling, long polling, and webhooks all work. What matters is that the API makes the right thing easy: a time filter (“messages received since X”), a sender filter, a cursor so you never re-read the same messages, and a documented polling interval. Without a time filter, tests that retry will eventually read a stale code.

6. What are the limits?

Every service has limits, and the good ones publish them. Check message size, attachment handling, messages per inbox, inbound rate per address, API rate per key, and daily caps, then compare them with how many inboxes and messages your tests or agents really need. Agent Temp Mail publishes all of its limits in llms.txt.

7. Does it work with agents?

If an AI agent will use the inbox, look for:

• An MCP server, so coding agents can use it as a tool.
• Function-tool definitions for the model APIs you call.
• A way to keep credentials out of the model’s context, such as signing requests in the host process.
• A read-only, GET-only path for chat assistants that can browse but can’t make arbitrary API calls.

8. Does it treat email as untrusted?

Email is attacker-controlled input. A service built for automation should never open links in messages, since visiting a link can confirm a subscription or complete someone else’s sign-in. It shouldn’t load remote images, and it should label message content as untrusted so an agent knows to treat it as data. Ask what happens to HTML, scripts, and attachments. For the agent’s side of this, see prompt injection by email.

Don’t forget domain blocking

Whatever you choose, some websites will refuse its domain. Lists of disposable domains are public and widely used at signup. For testing your own app that doesn’t matter, because you control the allowlist. For agents signing up for third-party services, it means some sign-ups will fail whichever provider you pick, and the honest fix is an address on a domain you own.

A checklist to copy

• Reading an inbox requires a credential scoped to that inbox.
• New inboxes are cheap enough to use one per test or task.
• Messages outlive your slowest flow, and the address lives as long as you need it.
• Messages are converted to text, with codes and links extracted in context.
• You can filter by time and sender, and paginate with a cursor.
• Limits are published and fit your volume.
• Agents can use it through MCP or function tools without seeing secrets.
• The service never visits links and marks content as untrusted.

How specific services compare

Applied to real services, the first question—who can read an inbox—already splits the market:

Checked 10 October 2026.

For the full picture, see temp mail for AI agents: twelve options compared, temp-mail.org alternatives with an API, and Mailinator, MailSlurp, and Mailosaur for agents.

Where Agent Temp Mail fits

Agent Temp Mail was designed against this checklist. Inboxes are free to create and never expire, every read is signed, codes and links are extracted with context, messages are labeled untrusted and never opened, and it plugs into agents through a local MCP server, a Node.js SDK and CLI, and a read link ChatGPT can open. Receive-only by design, so an inbox can never be used to send.

Need an inbox for an agent or a test right now? Open one, or see how to use it in Playwright tests.