Temp Mail API: Free Disposable Email API for Testing (2026)

Every signup flow you build has the same untestable seam: the email step. Your test fills the form, clicks submit, and then waits for a verification code that lives in an inbox your test suite cannot open, so the test gets skipped, stubbed, or handed to whoever is willing to check a shared Gmail account by hand.

A temp mail API closes that seam. Your test creates a real inbox, uses that address in the signup form, polls for the incoming message, pulls the code out of the body, and finishes the flow — without a human, a browser tab, or a shared mailbox anyone can pollute.

Short version: the Best-TempMail Developer API creates disposable inboxes over HTTP and returns their messages as JSON. The free tier needs no signup and no API key — you can call it in the next thirty seconds. Inboxes created through the API stay live for two hours, which is long enough for multi-step onboarding flows that a ten-minute browser inbox would miss.

If you already know you need production volume: the Founders plan is $19.99 for a full year and is capped at the first 100 developers. Same 2,000 requests/hour as the monthly Developer plan, billed once annually, and your rate stays locked for as long as the subscription is active. See plans.

What a disposable email API is actually for

It is not a spam tool, and it is not the browser-based temp mail most people use. The three jobs it does well are all engineering jobs.

Automated signup and onboarding tests. End-to-end suites that stop at "check your email" are testing half a flow. With a programmatic inbox, the test can complete registration, confirm the address, and assert on what the user actually receives.

CI/CD pipelines. Every run needs a fresh, uncontaminated address. Reusing one mailbox across runs means yesterday's message can satisfy today's assertion, which produces the worst kind of test: one that passes for the wrong reason.

Transactional email verification. Password resets, invoices, magic links, welcome sequences: anything you send is something you should be able to read back and assert on. Checking that the reset email actually contains a working link is a test, not a manual chore.

Third-party integration testing. When you build against someone else's signup flow, you need throwaway accounts on demand. Doing that with real inboxes means either polluting a work address or creating accounts you cannot clean up.

Quickstart: an inbox in two calls

The whole API lives under https://api.best-tempmail.com/v1 and returns JSON. Create an inbox, then read it.

Create an inbox with a random address:

curl -X POST https://api.best-tempmail.com/v1/inboxes

{
  "success": true,
  "address": "[email protected]",
  "created_at": "2026-08-14 20:00:00",
  "expires_at": "2026-08-14 22:00:00"
}

Then read its messages:

curl https://api.best-tempmail.com/v1/inboxes/[email protected]/messages

That is the entire flow. No account, no key, no OAuth dance.

If you want a specific prefix or domain, pass them — both are optional:

curl -X POST https://api.best-tempmail.com/v1/inboxes \
  -H "Content-Type: application/json" \
  -d '{"username":"signup-test-42","domain":"alagen.site"}'

One habit worth building in early: fetch the domain list at runtime rather than hardcoding it, because the available domains rotate over time.

curl https://api.best-tempmail.com/v1/domains

The endpoint you will actually write: polling for a code

Listing messages returns summaries. To get the body, fetch a single message by its ID. In practice you wrap both in a poll-until-arrival helper, and that helper is most of the integration.

Node, with no dependencies:

const BASE = "https://api.best-tempmail.com/v1";

async function createInbox() {
  const res = await fetch(`${BASE}/inboxes`, { method: "POST" });
  const data = await res.json();
  return data.address;
}

async function waitForCode(address, { timeoutMs = 60000, intervalMs = 2000 } = {}) {
  const deadline = Date.now() + timeoutMs;

  while (Date.now() < deadline) {
    const list = await (await fetch(`${BASE}/inboxes/${address}/messages`)).json();

    if (list.messages?.length) {
      const id = list.messages[0].id;
      const full = await (await fetch(`${BASE}/inboxes/${address}/messages/${id}`)).json();
      const match = full.message.text?.match(/\b(\d{4,8})\b/);
      if (match) return match[1];
      return full.message; // no numeric code — hand the message back
    }

    await new Promise((r) => setTimeout(r, intervalMs));
  }

  throw new Error(`No message arrived for ${address} within ${timeoutMs}ms`);
}

The same thing in Python:

import re, time, requests

BASE = "https://api.best-tempmail.com/v1"

def create_inbox() -> str:
    return requests.post(f"{BASE}/inboxes", timeout=15).json()["address"]

def wait_for_code(address: str, timeout: int = 60, interval: int = 2):
    deadline = time.time() + timeout
    while time.time() < deadline:
        msgs = requests.get(f"{BASE}/inboxes/{address}/messages", timeout=15).json()
        if msgs.get("messages"):
            mid = msgs["messages"][0]["id"]
            full = requests.get(
                f"{BASE}/inboxes/{address}/messages/{mid}", timeout=15
            ).json()["message"]
            found = re.search(r"\b(\d{4,8})\b", full.get("text") or "")
            return found.group(1) if found else full
        time.sleep(interval)
    raise TimeoutError(f"No message for {address} after {timeout}s")

Two details that save debugging time. Poll every two to three seconds rather than in a tight loop — the free tier allows 150 requests per hour, and a one-second poll burns through that in under three minutes. And set a real timeout: senders sometimes queue transactional mail for a minute or more under load, so a ten-second test will fail for reasons that have nothing to do with your code.

Reading the rate limit headers

Every response carries its own limits, so you can throttle before you get throttled rather than after.

X-RateLimit-Limit is your hourly ceiling. X-RateLimit-Remaining counts down within the current window. X-RateLimit-Reset is the Unix timestamp when it refills. X-Request-ID uniquely identifies the call and is the single most useful thing to quote if you ever email support about a specific failure.

In a CI pipeline, reading X-RateLimit-Remaining and backing off when it drops below a threshold is a five-line change that prevents an entire failed build.

What this API does not do

Being clear about the boundaries saves you from designing around capabilities that are not there.

It is receive-only. You cannot send outbound mail through it. That is a deliberate abuse constraint — allowing outbound would turn the service into a spam relay and destroy the domain reputation that makes incoming delivery work in the first place.

Inboxes expire after two hours. Longer than the browser-based 10 minute mail, long enough for a multi-step onboarding sequence, and not a place to store anything. When an inbox expires, its messages are gone and mail sent to it stops being accepted.

The free tier caps inbox creation at three per day per IP. This matters more than the request limit for CI use: a pipeline that creates a fresh inbox on every run will hit that ceiling quickly on a shared runner IP. The free tier is built for evaluation and light use, not for a build server running fifty times a day. If that is your use case, the paid tier exists for exactly that reason.

It is not a mailbox for anything you need to keep. No account recovery, no archive, no receipts. The same rule that applies to disposable addresses generally applies here — anything you might need next week belongs in a permanent inbox. Our guide on when temp mail is the wrong tool covers where that line sits.

Domains can still be rejected by some platforms. Aggressive signup filters block known disposable domains, which is why the domain pool rotates. If a specific service refuses your address, this breakdown of how detection works explains what is happening on their end.

Free tier, and when to move past it

The free tier is genuinely free: no signup, no key, no card. It allows 150 requests per hour with a burst limit of 100 per 10 seconds, and three new inboxes per day from a given IP. For evaluating the API, prototyping a test, or running a handful of checks, that is enough.

The paid tiers raise the hourly limit to 2,000 requests with a 300-per-10-seconds burst, and are what you want for a pipeline that runs continuously.

There are two ways to get those limits, and the difference is only how you pay. Developer is $19.99 per month. Founders is $19.99 per year for the same limits, which works out to roughly what the monthly plan costs in a fortnight. Founders is capped at the first 100 developers and your rate stays locked while the subscription is active, so it is worth taking early if the API fits your workflow. Paid plans authenticate with an x-api-key header, and the key is issued instantly on subscribing — there is still no account to create.

curl -X POST https://api.best-tempmail.com/v1/inboxes \
  -H "x-api-key: btm_sk_live_your_key_here"

Full endpoint reference, error codes, and copy-paste examples in four languages are on the API documentation page. If you need to inspect a domain's mail configuration while debugging delivery, the free email tools cover SPF, DKIM, DMARC and MX lookups.

How this compares to the alternatives

A shared team Gmail account

Cost: free. Isolation: none — every run reads the same mailbox, so tests can pass on a stale message. Automation: requires OAuth setup and Gmail API quotas. Verdict: works until two tests run at once, then produces flaky failures nobody can reproduce.

Plus-addressing on a real domain

Cost: free if you already have the domain. Isolation: partial — addresses are unique but all mail lands in one inbox, and many signup forms now strip or reject + addresses. Automation: still needs IMAP or a mail API. Verdict: fine for manual testing, awkward to automate, and increasingly filtered.

Commercial email-testing platforms

Cost: typically $9 to $99 per month. Isolation: excellent, with per-test inboxes and rich assertion tooling. Automation: mature SDKs and framework integrations. Verdict: the right answer for large QA teams with budget; more product than most projects need for verifying that a code arrives.

The Best-TempMail API

Cost: free to start, $19.99/year on the Founders tier. Isolation: a fresh inbox per call, two-hour lifetime. Automation: plain HTTP and JSON, no SDK required, no key on the free tier. Verdict: the fastest path from "I need to test this" to working code, with the free-tier inbox cap as the main constraint to plan around.

Frequently asked questions

Is the temp mail API really free with no signup?

Yes. The free tier requires no account, no API key, and no payment details — you send a POST to the inboxes endpoint and get an address back. The limits are 150 requests per hour and three new inboxes per day per IP. Paid plans exist for higher volume and add an x-api-key header, but nothing is gated behind a signup form.

How long does an inbox created through the API last?

Two hours from creation, which is longer than the ten-minute inbox on the website. That window is deliberate: multi-step onboarding flows often send a second email well after the first, and a ten-minute inbox expires before it arrives. Once the two hours are up, the inbox stops accepting mail and its messages are deleted.

Can I use this in a CI/CD pipeline?

Yes, and it is one of the main use cases — but plan around the free tier's three-inboxes-per-day-per-IP cap. Shared CI runners often present a single outbound IP, so a pipeline creating a fresh inbox per run will hit that ceiling fast. Either reuse one inbox across the runs in a session, or use a paid tier for continuous builds.

Can I send email through the API?

No. The service is receive-only by design. Allowing outbound mail would make it usable as a spam relay, which would get the sending domains blacklisted and break incoming delivery for everyone — the opposite of what makes the service useful.

What happens if a verification code never arrives?

Usually the target platform detected a disposable domain and silently dropped the message rather than returning an error. Fetch a different domain from the /v1/domains endpoint and retry, since the pool rotates. Our guide on why verification emails fail to arrive walks through the other causes, including greylisting and sender-side queue delays.

What is the Founders plan, and is it worth it?

Founders is $19.99 per year for 2,000 requests/hour and a 300-per-10-seconds burst, which is identical to the $19.99-per-month Developer plan. The difference is billing: a year of Founders costs about what two weeks of Developer does. It is limited to the first 100 developers, and the rate stays locked while the subscription is active. If the free tier's three-inboxes-per-day cap is blocking a pipeline, it is the cheaper of the two routes to the same limits.

Do I need an SDK?

No. Every endpoint is plain HTTP returning JSON, so the standard library of any language is enough — fetch in Node, requests in Python, curl in a shell script. The documentation includes working examples in curl, Node, Python, and PHP for each endpoint.