Free Domain Mail’s free temp mail API gives your code private temporary email inboxes: create addresses, wait for an OTP code or verification link, read and delete mail — no browser needed. Built for QA, sign-up flow tests, and scripts that need the code from an email. The API does not send mail; signed-in members send and reply from the web inbox and the app.
Create addressesOn .info, .link, inboxlumo.com or your own domain.
Wait for a codeOne call waits up to 60 seconds and returns the code.
Get the verify linkVerification links are extracted for you.
Every address @yourdomain (catch-all), nothing to create first
Mail is kept
7 days
90 days
Create / delete with the API
POST /addresses, DELETE /addresses/{id}
Connect the domain on the website (needs MX + TXT records)
The anonymous 10-minute temp mail cannot be read with the API. To use one of those addresses, keep it in your account first: POST /addresses with its domain and name.
3. Authentication
Base URL for every request:
https://freedomainmail.com/api/v1
Every request must carry an Authorization header with your key:
Requests and responses are JSON. A missing, invalid, or revoked key returns 401 with code unauthorized. Only a hash of the key is stored; if you lose it, create a new one and revoke the old one. Never ship a key in browser or mobile app code.
The member addresses you hold, the domains you can create them on, and your address limit. receiving = false means that domain no longer takes new mail (old mail stays readable).
One of the domains from GET /addresses. Left out → the first one.
name
The part before @. Letters, digits, dot, dash, underscore; 6–40 characters on freedomainmail.info/.link, 4–40 on inboxlumo.com. Left out → a random, memorable name.
Returns 201 with the address (same shape as in GET /addresses). Common errors: name_taken (409, held by someone or released recently), name_invalid (400), name_busy (409, the address is receiving public temp mail — retry in 10 minutes), limit_reached (409, you hold 100 addresses), daily_limit (429, enough new addresses for today).
DELETE/api/v1/addresses/{id}
Deletes the address and all its mail. Returns 204. The name stays locked for 90 days (nobody can take it), so for repeated test runs keep one address and reuse it instead of creating and deleting each time.
Fetches one message in full, including sanitized HTML, plain text, headers, attachment metadata, and extracted links. Remote images inside the HTML are blocked by default; add ?images=1 to keep them.
Deletes a single message (returns 204 No Content), or every message for one address — handy to reset an inbox between test runs. The address itself stays.
Waits for and returns the latest OTP code sent to an address. address is required. An address outside your account always ends in 404; the ownership check answers immediately only when wait > 0 (with wait=0 the lookup simply finds nothing, same result). wait is 0–60 seconds (larger values are clamped to 60); a timeout returns 404 with code not_found.
Optional pattern: point at the code in your own mail instead of relying on auto-detection. It is plain text (not a regex) with exactly one {code} (3–16 letters, digits or inner hyphens) or {digits} (3–12 digits) marking where the code sits, up to 200 characters. Matching is case-insensitive and spaces are flexible. For a mail body of key là : 5599292 and code là : 9292992, pattern=key là : {code} returns 5599292 and pattern=code là : {code} returns 9292992 (URL-encode the value). The pattern is applied to the text, then the HTML, then the subject of your 25 newest matching messages. An invalid pattern returns 400 with code invalid_request. Without pattern we auto-detect the code.
Same parameters as /code, but waits for and returns the latest verification link instead. primary is the link we picked as the confirmation link; links holds every verification link found.
The listing, code, and link endpoints share the same query parameters. /code and /links always return the single latest match, so they ignore limit and cursor.
Parameter
Meaning
address
Full recipient address, e.g. qa.signup@inboxlumo.com.
domain
Restrict results to one domain.
from
A full address matches exactly. A bare domain matches that domain and its subdomains: from=facebookmail.com matches mail from security@facebookmail.com, but from=facebook.com does not match @facebookmail.com.
subject
Case-insensitive substring match against the subject line.
q
Case-insensitive substring search over the subject, sender address, sender name and recipient.
since
ISO 8601 timestamp, or Unix time in seconds or milliseconds. Only messages received at or after this time are returned. It is compared to the server time when the message was received, so allow for clock skew on your side.
limit
Page size, up to 100. Defaults to 50. Listing only.
cursor
Pass back the next_cursor from a previous response to get the next page. Listing only.
6. Complete examples
Scenario: test a sign-up flow with an email OTP. Reuse one address you created (FDM_ADDRESS), note the start time (since), trigger the code on your site, then wait up to 30 seconds for it.
import os
import sys
import time
import requests
API = "https://freedomainmail.com/api/v1"
HEADERS = {"Authorization": "Bearer " + os.environ["FDM_KEY"]}
ADDRESS = os.environ["FDM_ADDRESS"] # e.g. ci.signup@inboxlumo.com
# 1. Note the start time so an older code is never picked up
since = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
# 2. ... fill ADDRESS into your sign-up form and press "Send code" ...
# 3. Wait up to 30 seconds for the code
response = requests.get(
API + "/code",
headers=HEADERS,
params={"address": ADDRESS, "since": since, "wait": 30},
timeout=40,
)
if response.status_code == 200:
print("Code:", response.json()["code"])
elif response.status_code == 404:
sys.exit("No code within 30 seconds")
elif response.status_code == 429:
sys.exit("Rate limited, retry after " + response.headers.get("Retry-After", "?") + "s")
else:
error = response.json()["error"]
sys.exit(f"{response.status_code} {error['code']}: {error['message']}")
60 requests per minute per key by default. Once exceeded, you get 429 with code rate_limited and a Retry-After header telling you how many seconds to wait.
5 concurrent wait requests per key at most. A sixth concurrent long-poll returns 429 with code too_many_waits.
Failed authentication is counted per IP address. After 20 failed attempts in one minute, every request from that IP (valid keys included) gets 429rate_limited until the one-minute window resets.
Member addresses: hold up to 100, create up to 20 new addresses per day per account (40 per IP). A deleted name stays locked for 90 days.
Mail is kept 7 days on member addresses and 90 days on your own domains, then expires automatically.
Usually the mail did not arrive within wait (raise wait or call again), since is later than the mail, the address has a typo, or the address does not belong to this key's account. Open the member inbox on the website to see whether the mail arrived.
The OTP is in the mail but /code does not find it?
Add a pattern that points at the code, e.g. pattern=Your code: {code}. Or read the mail with GET /messages/{id} and extract it yourself.
Can I send mail with the API?
Not yet. The API is for reading mail; members send limited mail from the web inbox or the app.
Which addresses can one key read?
Every member address you hold and every address on your own domains. You can create up to 10 keys, e.g. one per CI environment.
What if a key leaks?
Open the API keys page, revoke that key and create a new one. A revoked key stops working at once.
How long is mail kept?
7 days on member addresses, 90 days on your own domains. Use DELETE /messages to remove it sooner.
10. Acceptable use
Only use this API for lawful testing and privacy purposes — QA, sign-up flow tests, and automated OTP or verification-link checks. Using the API for fraud or to violate a third party’s terms of service leads to account suspension. Read the full acceptable use policy.