Free REST API for temporary inboxes
Free temp mail API for OTP codes and verification links
Create a private temporary address with one API call, or use any address at a domain you own, then read the result with one more: the latest verification code, the confirmation link, or the full message. Long-polling waits for the email, so your test needs no sleep loops.
Free · No paid plans · Unlimited domains · Bearer API key · 60 requests per minute per key
From zero to first code
- Create a free account and an API key. Sign-up is instant. In the app, open API and create a key, then send it as Authorization: Bearer YOUR_API_KEY.
- Get an address. No domain needed: POST /api/v1/addresses creates a private address on a Free Domain Mail domain such as inboxlumo.com. If you connect a domain you own, every address at it already works.
- Trigger the email. Sign up, log in or request a code on the site you are testing, using that address.
- Fetch the code or link. Call /api/v1/code or /api/v1/links with the address and wait=60; the request returns as soon as the email arrives.
Two kinds of API inbox
| Member address (no domain needed) | Your own domain | |
|---|---|---|
| Setup | One API call: POST /api/v1/addresses | Add one TXT and one MX record, once |
| Which addresses receive mail | Only the addresses you created | Every address at the domain (catch-all) |
| Mail kept | 7 days | 90 days |
| Who can read it | Only your account and its API keys | Only your account and its API keys |
| Best for | Getting started; a few fixed test inboxes reused with since | A fresh address for every test run and parallel CI jobs |
Endpoints
POST /api/v1/addresses, GET /api/v1/addresses and DELETE /api/v1/addresses/{id} — create, list and delete private member addresses.
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} or DELETE /api/v1/messages?address=… removes mail.
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.
What this API is, and what it is not
It reads real email that has been delivered over the internet to an inbox you own. That makes it suited to sign-up, login and password-reset tests, and to checking mail sent by services you do not control.
It is not an SMTP sandbox that traps your app's outgoing mail before delivery, it does not send email, and it has no SMS, HTML-rendering or spam-score checks. The Mailtrap, Mailosaur and Mailinator comparison pages say when those tools are the better fit.
The anonymous 10-minute temp mail on the homepage cannot be read through the API, because anyone can open it. Keep the address in your account first and it becomes private. New member addresses are capped per day, so for many runs reuse one address and pass since, or connect a domain where every address works with no creation step.
Examples
Replace YOUR_API_KEY with your key and test@yourdomain.com with your member address or an address on your connected domain.
curl -X POST "https://freedomainmail.com/api/v1/addresses" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"domain": "inboxlumo.com", "name": "qa.signup"}'curl -G "https://freedomainmail.com/api/v1/code" \
-H "Authorization: Bearer YOUR_API_KEY" \
--data-urlencode "address=test@yourdomain.com" \
--data-urlencode "wait=60"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"])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 is free, with no paid plans. Create private addresses on Free Domain Mail domains with POST /api/v1/addresses, or connect domains you own, with no limit on how many, where every address works.
Do I need my own domain?
No. Member addresses work without one. A domain you own adds catch-all addresses, so each test can use a brand-new address, and keeps mail for 90 days instead of 7.
Does the API work with the public temp mail on the homepage?
Not with the anonymous 10-minute inbox, which anyone who knows the address can open. Keep the address in your account with POST /api/v1/addresses, using its domain and name, and the API can read it privately.
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, a few waiting requests per key at the same time, and wait holds a request for at most 60 seconds.
Can the API send email?
No. The API only reads incoming mail. Signed-in members can send and reply on the web and in the app, but there is no sending API and no SMTP access, so your app keeps its own email provider.
Is it a replacement for Mailtrap or Mailosaur?
For receiving real email and reading codes and links, often yes. It is not an SMTP capture sandbox and has no SMS, HTML-rendering or spam checks; the comparison pages explain when those tools fit better.