Developers 9 min read

Temp Mail API: How It Works and How the Main APIs Compare

Pokemail Team Published Updated Checked (how we check)
Code brackets containing an email envelope representing temporary email API for developers
đź“‘ 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.

StepWhat your code doesPokemail’s endpoint
1. CreateAsks for a new addressPOST /api/v1/addresses
2. UseSubmits the address to the form or service under test(your own code)
3. ReadLists the inbox, then fetches the message it needsGET /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.

APIHow you get accessThe addressHow you learn of new mailRate limit, as published
PokemailA key from your dashboard, sent as Authorization: BearerA random 7-character name at a domain your key may use, with an encrypted second address that reaches the same inboxList the inbox, or a webhook signed with HMAC-SHA256Calls a minute and calls a day, both in the headers of every call it accepts
Temp-Mail.orgThrough RapidAPIAny 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 messageNot on its API page; its documentation is on RapidAPI
Mail.tmNo API key and no signupAn account you create with an address and a password, then a tokenList the messages, or listen with server-sent events (SSE)8 queries per second per IP address
Guerrilla MailPublic, with a session cookieA random name, or any name you setCall check_emailNot published
TempMail.lolNo key for the free tierAn address with an access token; one hour free, ten hours on Plus, thirty on UltraFetch emails, or webhooksA “Usage & Quota” section in its API v3 documentation
MailinatorAn API subscriptionAny name at a private domain of yours; the public domain is readable by anyoneFetch 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.

PollingWebhook
How it worksYour code asks the inbox every few secondsThe service sends a POST to your server when mail arrives
SpeedAs fast as your intervalAs soon as the message lands
Calls usedOne per checkNone for waiting
NeedsNothing moreA 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:

HeaderWhat it tells you
X-RateLimit-Limit, X-RateLimit-RemainingYour calls a minute, and how many are left
X-Pokemail-Calls-Limit, X-Pokemail-Calls-Remaining, X-Pokemail-Calls-ResetYour 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.

CheckerHow you call itWhat it answersSource
Kickbox OpenGET https://open.kickbox.com/v1/disposable/{domain or email}{"disposable":true} or falseopen.kickbox.com
DeBounceGET https://disposable.debounce.io/?email={address}{"disposable":"true"} or "false", as a stringdebounce.com
disposable-email-domainsA plain list you load and check yourselfA match or no matchGitHub, 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 needLook for
Codes in CI/CD, fastWebhooks, or delivery in real time
Many tests in parallelPublished limits in the headers of every answer
Your own address spaceMore than one domain, or a private domain
Proof a request is genuineSigned webhooks
Nothing to sign up forAn 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.

đź“§
Try Pokemail

Free temporary email in one click. No registration, no tracking. Auto-deletes in 60 minutes.

Get Your Inbox →

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

  1. Temp-Mail.org temp-mail.org
  2. Mail.tm docs.mail.tm
  3. Guerrilla Mail guerrillamail.com
  4. TempMail.lol tempmail.lol
  5. Mailinator mailinator.com
  6. MailSlurp mailslurp.com
  7. Mailosaur mailosaur.com
  8. open.kickbox.com open.kickbox.com
  9. debounce.com debounce.com
  10. 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.