REST API for disposable inboxes

Temp mail API for OTP codes and verification links

Connect a domain, use a new address in every test, and read the result with one HTTP call: the latest verification code, the confirmation link, or the full message. Long-polling waits for the email so your test does not need sleep loops.

Get an API key →Read the API docs

First domain free · Bearer API key · 60 requests per minute per key

From zero to first code

Connect a domain. Add a domain you own and publish the TXT and MX records. Every address at it becomes a catch-all inbox.
Create an API key. In the app, open API and create a key. Send it as Authorization: Bearer YOUR_API_KEY.
Use a fresh address per test. Sign up with signup-<random>@yourdomain.com — no need to create it first.
Fetch the code or link. Call /api/v1/code or /api/v1/links with the address, and add wait=60 to block until the email arrives.

Endpoints

GET /api/v1/code — latest one-time code for an address. Options: wait (up to 60 seconds), pattern (plain text with one {code} or {digits}), from, subject, since.

GET /api/v1/links — verification and action links from the latest email.

GET /api/v1/messages and GET /api/v1/messages/{id} — list and read full messages; DELETE /api/v1/messages/{id} removes one.

GET /api/v1/domains — your connected domains and whether they are accepting mail.

Exact codes with pattern

When an email contains several numbers, pass the text around the code: pattern=Your code is {code}. The text is matched literally (not as a regex), case-insensitively and with flexible spacing, against the 25 most recent messages for that address.

Examples

Replace YOUR_API_KEY with your key and test@yourdomain.com with an address on your connected domain.

curl — wait for the next code

curl -G "https://freedomainmail.com/api/v1/code" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "address=test@yourdomain.com" \
  --data-urlencode "wait=60"

Python — exact code with pattern

import requests

r = requests.get(
    "https://freedomainmail.com/api/v1/code",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    params={"address": "test@yourdomain.com", "pattern": "Your code is {code}", "wait": 60},
    timeout=70,
)
r.raise_for_status()
print(r.json()["code"])

Playwright (TypeScript) — sign-up test

const address = `signup-${Date.now()}@yourdomain.com`;
await page.fill("#email", address);
await page.click("text=Send code");

const res = await fetch(
  `https://freedomainmail.com/api/v1/code?address=${encodeURIComponent(address)}&wait=60`,
  { headers: { Authorization: "Bearer " + process.env.FDM_API_KEY } },
);
if (!res.ok) throw new Error(`code not received: ${res.status}`);
const { code } = await res.json();
await page.fill("#otp", code);

Common questions

Is there a free temp mail API?

Yes. The API works on custom domains, and the first domain is free.

Does the API work with the public temp mail domains?

No. The API reads inboxes on domains connected to your account, which keeps codes private to you.

How do I avoid picking up an old code?

Use a new address per test run, or pass since with the time the test started.

What are the rate limits?

60 requests per minute per API key, and wait holds a request for at most 60 seconds.

Can the API send email?

No. Free Domain Mail is receive-only.

Get an API key →