How temp mail providers actually work (Mail.tm, Mail.gw, Maildrop explained)

For most users, "temp mail" is a black box: hit a button, get an inbox, see emails. For engineers building tools on top, the box has interesting structure. This post walks through how the major free providers are built, what their APIs look like, and what each does best. If you're integrating with them — or just curious — start here.

Why this matters

Temp-mail providers vary enormously in how they handle three concerns: address allocation (how the address comes into existence), storage and retrieval (where messages live and how you read them), and real-time delivery (whether you have to poll, or whether the provider pushes updates to you). Each design tradeoff has consequences for latency, scale, and what users perceive as "reliability."

Mail.tm

Mail.tm is the gold standard of free temp-mail APIs. It's been live since around 2018, the API is documented (Hydra/JSON-LD), CORS is enabled so it can be called directly from a browser, and real-time delivery is supported through Mercure-protocol Server-Sent Events.

Address allocation

Mail.tm exposes GET /domains with a paginated list of currently active domains (filterable by isActive and isPrivate). To create an address, you POST /accounts with { address, password }. The password is a credential you chose at creation time — Mail.tm stores it for later authentication. The address must use one of the currently active domains. The local-part you choose is yours.

Then you POST /token with the same address and password to get a JWT, which you pass on every subsequent call as Authorization: Bearer <jwt>.

Storage and retrieval

Messages are stored on Mail.tm's servers up to a 40 MB quota per account. Inactive accounts are purged after about seven days. GET /messages returns paginated summaries (preview, sender, subject); GET /messages/{id} returns the full body, including attachments.

One small but important detail: the html field on a message is an array of strings, not a single string. Forgetting this is, in the team's experience, the most common Mail.tm integration bug. You always render html.join("").

Real-time delivery

Mail.tm pushes new-message notifications via a Mercure hub at https://mercure.mail.tm/.well-known/mercure. Subscribe to ?topic=/accounts/{id} with the bearer token (most browser EventSource implementations cannot send headers; we use @microsoft/fetch-event-source instead). When a message arrives, the server emits an event whose payload is the updated Account resource. The event is essentially a "go fetch" ping; you still call GET /messages to get the full content.

Rate limiting

Mail.tm enforces 8 requests per second per IP across all endpoints. This is generous for individual users; for an aggregator that proxies through a single IP, it's the bottleneck. Best practice: call from the user's browser when CORS allows, so each user's IP gets its own budget.

Mail.gw

Mail.gw is, mechanically, a clone of Mail.tm. It exposes the same API surface at https://api.mail.gw with a different domain pool. Why does it exist? Pure redundancy. If Mail.tm has an outage or rate-limits you, you can switch to Mail.gw and use exactly the same client code with one base-URL change. We weight Mail.gw at about half the weight of Mail.tm in our auto-pick to keep load distributed.

Guerrilla Mail

The veteran. Live since 2007. Stylistically the most "old-web" — its API is essentially ?f=<function> over api.guerrillamail.com/ajax.php, with eleven languages, multiple domains, and a quirky session model. CORS is not enabled, so you have to proxy from your own server. Custom local-parts are well supported via set_email_user.

Address allocation

get_email_address returns a fresh address and a sid_token. The sid_token is the session credential — you pass it on every subsequent call. To switch to a custom local-part: set_email_user with email_user=yourname and the same sid_token. The available domains include sharklasers.com, grr.la, guerrillamail.org, pokemail.net, and several more.

Storage and retrieval

Messages are kept for about an hour by default; extend lengthens the address. get_email_list returns summaries; fetch_email returns a single message (with its content type, so you know whether to render HTML or plain text). del_email removes a message; forget_me burns the address.

Real-time delivery

Guerrilla Mail uses a long-poll endpoint check_email with a seq cursor that advances as new messages arrive. The pattern is essentially "ask, wait up to N seconds, return any new messages, repeat." Latency is fine — 5–10 seconds typical — but it's polling, not push.

Maildrop

The "fun" one. Maildrop is open source (GitHub) and offers a single domain, maildrop.cc, which is catch-all: any local-part you make up immediately exists. There is no "create" call. You just decide on a username and start reading mail.

API

GraphQL, queries only. inbox(mailbox: String!): [Message!] lists messages by local-part; message(mailbox, id) reads one; delete(mailbox, id) removes one. There's also altinbox(mailbox), which suggests a slightly less guessable alternative spelling for the same effective inbox.

Privacy implications

Because Maildrop is catch-all, anyone who guesses the local-part can read your mail. Don't pick support@maildrop.cc and expect privacy. For one-off verifications this is rarely a concern; for anything else it is.

Real-time

None. Polling only.

TempMail.lol

Modern, simple, REST-based. POST /inbox/create returns { address, token }. GET /inbox?token=… returns messages. Free tier inboxes last about an hour; lose the token, lose the inbox. The API is small enough to integrate in an afternoon.

The aggregation pattern

Once you've integrated more than two or three providers, an aggregation layer pays for itself many times over. The shape we use:

• A single MailProvider TypeScript interface. listDomains, createInbox, listMessages, getMessage, deleteMessage, optional deleteInbox and subscribe.
• A token-bucket rate limiter, in-memory, keyed by (provider, ip). When a provider returns 429, the bucket goes to zero for sixty seconds and we fail over to the next available provider.
• A weighted-random picker for the "Auto" mode: Mail.tm 35, Mail.gw 25, Guerrilla 20, Maildrop 13, TempMail.lol 7, plus tertiary providers as 1-weight fallbacks.
• An always-on polling backstop alongside any SSE/WS subscription. SSE/WS connections silently die in background tabs, on cellular handovers, and in front of certain corporate proxies. Don't trust them alone.
• Aggressive caching of listDomains — five minutes is sane. Domains rotate slowly.

What we deliberately don't aggregate

Several providers in our research dossier are dead, undocumented, or scraped against the operator's wishes:

• 1secmail has been returning 403 since late 2024.
• Getnada / nada.cc is parked.
• Yopmail, Generator.email, EmailFake, Mohmal have no public APIs; the available "wrappers" scrape, which the operators explicitly forbid.
• Mailinator's free public tier is web-only.

Our codebase keeps these listed as "deprecated" rather than silently omitting them, so future readers don't repeat the research.

Closing thoughts

Free temp-mail APIs are unsung infrastructure. They keep millions of inboxes from drowning in marketing email and meaningfully raise the cost of email-based fraud (because senders can't trust that an inbox represents a person). The good ones charge nothing, document well, and respect their users' time. If you're building on top, pick at least three; design for failover; respect each provider's rate limit; and link back to them.

Want to see the result of doing all this for the user-facing layer? Try generating an inbox now.