Temp Mail API: How It Works and How the Main APIs Compare
In This Article
A temp mail API is an HTTP interface that creates a disposable email address and lets your code read the mail that arrives at it. It is how automated tests, CI/CD pipelines and signup flows get a real, working inbox for every run without a human copying codes by hand.
This page explains how such an API works and compares the main ones, each from its own public page as read on November 14, 2026. To make your first call to the Pokemail API, follow the developer API quickstart: it has the requests to make an address and to list and read its mail in curl, JavaScript and Python.
What does a temp mail API do?
Every temp mail API does the same three things.
| Step | What your code does | Pokemail’s endpoint |
|---|---|---|
| 1. Create | Asks for a new address | POST /api/v1/addresses |
| 2. Use | Submits the address to the form or service under test | (your own code) |
| 3. Read | Lists the inbox, then fetches the message it needs | GET /api/v1/inbox/:address, then GET /api/v1/email/:id |
The inbox lasts a short time and is then gone, like the burner or throwaway inbox a person opens in the browser. Nothing has to be cleaned up after a test, and no test shares an inbox with another.
The most common uses are end-to-end tests of signup and onboarding, checking that password resets and invoices are sent, QA across many test accounts at once, and checking email delivery in a CI/CD pipeline. If you test signup flows by hand first, our guide on using disposable email for signups covers the manual process.
How do the main temp mail APIs compare?
Each row says what the service’s own page says today.
| API | How you get access | The address | How you learn of new mail | Rate limit, as published |
|---|---|---|---|---|
| Pokemail | A key from your dashboard, sent as Authorization: Bearer | A random 7-character name at a domain your key may use, with an encrypted second address that reaches the same inbox | List the inbox, or a webhook signed with HMAC-SHA256 | Calls a minute and calls a day, both in the headers of every call it accepts |
| Temp-Mail.org | Through RapidAPI | Any name at one of its domains; incoming mail “deleted within 1-2 hours” | Request the list of emails, then a message by its ID, as JSON or as the raw message | Not on its API page; its documentation is on RapidAPI |
| Mail.tm | No API key and no signup | An account you create with an address and a password, then a token | List the messages, or listen with server-sent events (SSE) | 8 queries per second per IP address |
| Guerrilla Mail | Public, with a session cookie | A random name, or any name you set | Call check_email | Not published |
| TempMail.lol | No key for the free tier | An address with an access token; one hour free, ten hours on Plus, thirty on Ultra | Fetch emails, or webhooks | A “Usage & Quota” section in its API v3 documentation |
| Mailinator | An API subscription | Any name at a private domain of yours; the public domain is readable by anyone | Fetch the inbox, or webhooks | ”Subject to your subscription plan’s rate limits” |
Two more services are built for testing teams rather than for disposable inboxes. MailSlurp offers email inboxes, custom domains and SMS numbers through an API. Mailosaur gives each inbox its own domain, for email and SMS testing, with a 14-day free trial.
Mail.tm’s terms add three rules: no reselling its API, no proxying it under another domain, and a visible link back to mail.tm. Guerrilla Mail’s API document is version 1.0 of April 19, 2011, and its addresses last 60 minutes.
How do you read a verification code from the API?
Read the subject first, because many codes are in it. Pokemail’s inbox list already carries each message’s subject and a short preview. Fetch the whole message only when the code or the link is in the body.
Codes come in a few shapes: a 4 to 8 digit number, a verification link, or a “magic link” with a token in it. Keep one small set of helpers, separate from your tests, so a changed email template means one fix in one place.
// Extraction helpers, kept apart from the tests
function extractNumericCode(text) {
const match = text.match(/\b(\d{4,8})\b/);
return match ? match[1] : null;
}
function extractVerifyLink(html) {
const match = html.match(/href="(https?:\/\/[^"]*verify[^"]*)"/i);
return match ? match[1] : null;
}
function extractMagicLink(html) {
const match = html.match(/href="(https?:\/\/[^"]*token=[^"]*)"/i);
return match ? match[1] : null;
}
When a helper finds nothing, log the whole message body. Templates change without warning, and the body tells you at once which pattern to fix.
Webhooks or polling: which should you use?
Use a webhook when the API offers one, and polling when it does not.
| Polling | Webhook | |
|---|---|---|
| How it works | Your code asks the inbox every few seconds | The service sends a POST to your server when mail arrives |
| Speed | As fast as your interval | As soon as the message lands |
| Calls used | One per check | None for waiting |
| Needs | Nothing more | A public HTTPS address for your server |
A Pokemail webhook is a POST with a JSON body holding event (new_email), a timestamp, and data with the address and the message’s summary. It carries X-Pokemail-Signature, the HMAC-SHA256 of the exact body in hex, made with the secret you were shown once when you created the webhook. Check it before you trust the request:
// Verify a Pokemail webhook (Node.js). rawBody is the request body exactly as received.
const { createHmac, timingSafeEqual } = require("node:crypto");
function isFromPokemail(rawBody, signatureHeader, secret) {
const expected = Buffer.from(createHmac("sha256", secret).update(rawBody).digest("hex"));
const given = Buffer.from(String(signatureHeader || ""));
return given.length === expected.length && timingSafeEqual(given, expected);
}
If you poll instead, wait 2 to 3 seconds between checks and stop after 30 to 60 seconds. A test that fails should say which happened: the email never arrived, or it arrived and the content did not match.
How do you use a temp mail API in CI/CD?
Put address creation, inbox reading and code extraction in one helper module, and call it from your test framework’s setup hooks. Jest, Playwright, Cypress and pytest all have them.
// Playwright: one fresh address per test, made by your own helper
const { test, expect } = require("@playwright/test");
test.beforeEach(async ({}, testInfo) => {
testInfo.tempEmail = await createTempAddress();
});
test("user can sign up and verify email", async ({ page }, testInfo) => {
await page.goto("/signup");
await page.fill("#email", testInfo.tempEmail);
await page.fill("#password", "TestPassword123!");
await page.click("#submit");
const emails = await waitForEmail(testInfo.tempEmail);
const code = extractNumericCode(emails[0].subject);
await page.fill("#verification-code", code);
await page.click("#verify");
await expect(page.locator(".welcome")).toBeVisible();
});
createTempAddress and waitForEmail are the create and read calls of the quickstart, wrapped in your own module.
Keep the API key in an environment variable or a secrets manager. Never commit it, and never print it in test output.
⚠️ Your API key can read every inbox it created. Treat it like any other credential: store it in a secrets manager, rotate it when you can, and give it only to the systems that need it.
Address comparison is a quiet source of false failures. If your test checks the address your application stored against the one the API gave you, fold both to lowercase first: the part before the @ can be case sensitive only where the receiving mail server makes it so, so a capitalized copy can fail a test that is actually passing.
How do rate limits work on a temp mail API?
Each API sets its own. Mail.tm publishes 8 queries per second per IP address. Guerrilla Mail says its API “may be rate limited” and does not publish the limits.
Pokemail counts two limits for each key and reports both in the headers of every call it accepts:
| Header | What it tells you |
|---|---|
X-RateLimit-Limit, X-RateLimit-Remaining | Your calls a minute, and how many are left |
X-Pokemail-Calls-Limit, X-Pokemail-Calls-Remaining, X-Pokemail-Calls-Reset | Your calls a day, how many are left, and when the count starts again (00:00 UTC) |
Retry-After (on a 429 answer) | How many seconds to wait |
GET /api/v1/usage gives today’s count as well. To stay inside a limit, reuse one address across tests that do not need isolation, create addresses at the start of a run rather than in a burst, and back off when an answer is 429.
Beyond Testing: Provisioning Accounts at Scale
The same address-creation-and-inbox-reading loop that powers automated tests also powers account provisioning. Anyone running a multi-accounting workflow (agencies with client accounts, e-commerce operators with multiple storefronts, marketers isolating campaigns) needs a unique, working email for every account, and generating them by hand doesn’t scale.
The API turns that into a pipeline. Your automation requests a fresh address, submits it to the signup form, polls the inbox for the verification code, and completes registration, no human in the loop. Paired with an antidetect browser that gives each account its own fingerprint, and proxies for IP separation, the Pokemail API becomes the email layer of a full provisioning stack. The three signals platforms use to link accounts (email, fingerprint, and IP) each get their own unique value per account.
The code is identical to the testing examples above; only the caller changes. Where a test asserts on the verification email, a provisioning flow clicks the verification link and stores the credentials.
What is a disposable email checker API?
A disposable email checker API answers one question: does this address belong to a temporary email provider? It is the other side of a temp mail API, used by sites that want to know which signups used a throwaway address.
| Checker | How you call it | What it answers | Source |
|---|---|---|---|
| Kickbox Open | GET https://open.kickbox.com/v1/disposable/{domain or email} | {"disposable":true} or false | open.kickbox.com |
| DeBounce | GET https://disposable.debounce.io/?email={address} | {"disposable":"true"} or "false", as a string | debounce.com |
| disposable-email-domains | A plain list you load and check yourself | A match or no match | GitHub, CC0 public domain |
How does a disposable email checker API work?
It takes the domain after the @ and looks it up in its list of known temporary email domains. The disposable-email-domains list held 10,181 lines on November 14, 2026. A domain that is not on a list yet is answered as not disposable, so no checker is complete.
// Example: check one address with Kickbox's free endpoint
const domain = "user@example.com".split("@").pop();
const res = await fetch(`https://open.kickbox.com/v1/disposable/${encodeURIComponent(domain)}`);
const { disposable } = await res.json(); // true or false
Sites use the answer for analytics, for fraud checks on marketplaces and payments, and to tell trial signups from lasting ones. If many of your trial signups use disposable email, that is also a sign your signup asks for more than people want to give.
Choosing the Right Temp Mail API
| If you need | Look for |
|---|---|
| Codes in CI/CD, fast | Webhooks, or delivery in real time |
| Many tests in parallel | Published limits in the headers of every answer |
| Your own address space | More than one domain, or a private domain |
| Proof a request is genuine | Signed webhooks |
| Nothing to sign up for | An API that needs no key |
For a broader comparison of temporary email services and their features, see our review of the best services available. For what makes a temporary inbox safe to use, and for why throwaway email exists at all, see those guides. For a quick start with the Pokemail API specifically, see our developer API quickstart guide.
Free temporary email in one click. No registration, no tracking. Auto-deletes in 60 minutes.
Frequently Asked Questions
What is a temp mail API?
A temp mail API lets you create disposable email addresses and read their inboxes from code, over HTTP. Developers use one to test signup and password-reset emails, and to check email delivery in CI/CD pipelines. The inbox and its mail last only a short time, like the burner or throwaway inbox of the same service.
Is there a free temp mail API?
Yes. Mail.tm's own documentation says its API is completely free, with no API key and no signup, at 8 queries per second per IP address. Guerrilla Mail publishes a public JSON API, and TempMail.lol needs no key for its free tier.
Does Temp-Mail.org have an API?
Yes. Temp-Mail.org's API page says it is offered through RapidAPI, for testing sign-ups and password resets with many disposable addresses. It lists mail at any address on its domains and returns each message as JSON, and its page says incoming mail is deleted within 1 to 2 hours.
What is a disposable email checker API?
A disposable email checker API tells you whether an address or domain belongs to a temporary email provider. You send the address or domain, and it answers with a true or false. Kickbox and DeBounce each offer a free endpoint, and the open disposable-email-domains list can be checked on your own server.
How does a disposable email checker API work?
It takes the domain after the @ and looks it up in a list of known temporary email domains. Kickbox's free endpoint answers {"disposable":true} for a listed domain, and DeBounce's answers {"disposable":"true"}. A domain that is not on the list yet is answered as not disposable.
Can I use webhook notifications instead of polling?
Yes, with an API that offers them. A webhook is a POST the service sends to your server when a message arrives, so your test does not have to ask the inbox again and again. Pokemail signs each webhook with HMAC-SHA256 in the X-Pokemail-Signature header, so your server can check that it came from Pokemail.
What are the best temp mail APIs for CI/CD?
Look for APIs with fast delivery via WebSocket, webhook support for real-time notifications, multiple domains for rotation, clear rate limit headers, and good documentation. Pokemail's API has sub-second email delivery and rate limit headers on every add-on, webhooks on Premium and Pro, and more domains on the higher add-ons.
Sources
- Temp-Mail.org temp-mail.org
- Mail.tm docs.mail.tm
- Guerrilla Mail guerrillamail.com
- TempMail.lol tempmail.lol
- Mailinator mailinator.com
- MailSlurp mailslurp.com
- Mailosaur mailosaur.com
- open.kickbox.com open.kickbox.com
- debounce.com debounce.com
- GitHub github.com
What this page says of another service comes from that service's own pages, and what it says of Pokemail from the service itself, checked on November 14, 2026. How we write and check our posts.