Free Domain Mail
REST API v1

Temp mail API documentation

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.

1. Quick start (3 steps)

Step 1 — Get an API key

  1. Create a free account (you are in right away, no email verification) or sign in.
  2. In the Member inbox, scroll to Get codes automatically with the API and press Create API key. If you connected your own domain: Manage → API.
  3. Name the key (e.g. CI runner) and copy it right away — it is shown only once.

The examples below read the key from the FDM_KEY environment variable:

bash
export FDM_KEY="fdm_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Step 2 — Create an address

Leave out name to get a random, memorable one. Mail to this address is kept for 7 days and only your keys can read it.

curl
curl -X POST https://freedomainmail.com/api/v1/addresses \
  -H "Authorization: Bearer $FDM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "inboxlumo.com", "name": "qa.signup"}'

Response:

201 Created
{
  "address": {
    "id": "5b1c2f0e-8a1d-4c3e-9f2a-7d6b1e0c4a91",
    "address": "qa.signup@inboxlumo.com",
    "domain": "inboxlumo.com",
    "created_at": "2026-10-31T08:00:00.000Z",
    "message_count": 0,
    "receiving": true
  }
}

Step 3 — Wait for the code

Sign up on the site you are testing with that address, then call /code. It waits up to 30 seconds and answers as soon as a mail with a code arrives.

curl
curl -G https://freedomainmail.com/api/v1/code \
  -H "Authorization: Bearer $FDM_KEY" \
  --data-urlencode "address=qa.signup@inboxlumo.com" \
  --data-urlencode "wait=30"
200 OK
{
  "code": "482913",
  "message_id": "8f6c9e2a-2a3b-4b7a-9b0e-2c1f3a9d7e11",
  "from": "no-reply@shop.example",
  "subject": "Mã xác minh của bạn là 482913",
  "received_at": "2026-10-31T08:01:12.000Z"
}

No mail within 30 seconds → 404 with code not_found. Just call again; see Errors.

2. Member addresses and your own domains

One API key reads mail for both kinds of address below. The mail endpoints (/messages, /code, /links) work the same for both.

Member addressesYour own domain
Domainsfreedomainmail.info, freedomainmail.link, inboxlumo.comA domain you own and connected to your account
Which addresses receive mailOnly the addresses you created (up to 100)Every address @yourdomain (catch-all), nothing to create first
Mail is kept7 days90 days
Create / delete with the APIPOST /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:

Authorization: Bearer fdm_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

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.

4. Endpoints

EndpointWhat it does
GET /addressesList your member addresses
POST /addressesCreate an address
DELETE /addresses/{id}Delete an address and all its mail
GET /domainsList your own domains
GET /messagesList messages, newest first
GET /messages/{id}Read one message in full
DELETE /messagesDelete mail
GET /codeWait for and return the latest OTP code
GET /linksWait for and return the latest verification link

GET /api/v1/addresses

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).

curl
curl https://freedomainmail.com/api/v1/addresses -H "Authorization: Bearer $FDM_KEY"
200 OK
{
  "addresses": [
    {
      "id": "5b1c2f0e-8a1d-4c3e-9f2a-7d6b1e0c4a91",
      "address": "qa.signup@inboxlumo.com",
      "domain": "inboxlumo.com",
      "created_at": "2026-10-31T08:00:00.000Z",
      "message_count": 3,
      "receiving": true
    }
  ],
  "domains": ["freedomainmail.info", "freedomainmail.link", "inboxlumo.com"],
  "limit": 100
}

POST /api/v1/addresses

Creates an address. JSON body:

FieldMeaning
domainOne of the domains from GET /addresses. Left out → the first one.
nameThe 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.
curl
curl -X POST https://freedomainmail.com/api/v1/addresses \
  -H "Authorization: Bearer $FDM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "freedomainmail.info"}'

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.

curl
curl -X DELETE https://freedomainmail.com/api/v1/addresses/5b1c2f0e-8a1d-4c3e-9f2a-7d6b1e0c4a91 \
  -H "Authorization: Bearer $FDM_KEY"

GET /api/v1/domains

The domains on your account and whether each is currently accepting mail. accepting_mail becomes true once its TXT and MX records are verified.

200 OK
{
  "domains": [
    {
      "domain": "yourdomain.com",
      "dns_status": "verified",
      "mx_verified": true,
      "accepting_mail": true,
      "created_at": "2026-08-01T09:00:00.000Z"
    }
  ]
}

GET /api/v1/messages

Messages for every address you can read, newest first, filtered with the shared filters. Up to 100 per page; next_cursor is set when there is more.

curl
curl -G https://freedomainmail.com/api/v1/messages \
  -H "Authorization: Bearer $FDM_KEY" \
  --data-urlencode "address=qa.signup@inboxlumo.com" \
  --data-urlencode "limit=20"
200 OK
{
  "messages": [
    {
      "id": "8f6c9e2a-2a3b-4b7a-9b0e-2c1f3a9d7e11",
      "recipient": "qa.signup@inboxlumo.com",
      "domain": "inboxlumo.com",
      "from_address": "security@facebookmail.com",
      "from_name": "Facebook",
      "subject": "Your confirmation code is 482913",
      "received_at": "2026-10-31T08:01:12.000Z",
      "expires_at": "2026-11-07T08:01:12.000Z",
      "otp_code": "482913",
      "primary_link": null
    }
  ],
  "next_cursor": null
}

GET /api/v1/messages/{id}

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.

200 OK
{
  "message": {
    "id": "8f6c9e2a-2a3b-4b7a-9b0e-2c1f3a9d7e11",
    "recipient": "qa.signup@inboxlumo.com",
    "domain": "inboxlumo.com",
    "from_address": "security@facebookmail.com",
    "from_name": "Facebook",
    "subject": "Your confirmation code is 482913",
    "received_at": "2026-10-31T08:01:12.000Z",
    "expires_at": "2026-11-07T08:01:12.000Z",
    "otp_code": "482913",
    "primary_link": null,
    "text": "Your confirmation code is 482913.",
    "html": "<p>Your confirmation code is 482913.</p>",
    "blocked_images": 0,
    "tracking_images": 0,
    "headers": { "message-id": "<abc@mail.facebookmail.com>" },
    "attachments": [],
    "links": []
  }
}

DELETE /api/v1/messages/{id} · /api/v1/messages?address=

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.

curl
curl -X DELETE -G https://freedomainmail.com/api/v1/messages \
  -H "Authorization: Bearer $FDM_KEY" \
  --data-urlencode "address=qa.signup@inboxlumo.com"
200 OK
{ "deleted": 3 }

GET /api/v1/code

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.

curl
curl -G https://freedomainmail.com/api/v1/code \
  -H "Authorization: Bearer $FDM_KEY" \
  --data-urlencode "address=qa.signup@inboxlumo.com" \
  --data-urlencode "wait=30" \
  --data-urlencode "pattern=key là : {code}"
200 OK
{
  "code": "482913",
  "message_id": "8f6c9e2a-2a3b-4b7a-9b0e-2c1f3a9d7e11",
  "from": "security@facebookmail.com",
  "subject": "Your confirmation code is 482913",
  "received_at": "2026-10-31T08:01:12.000Z"
}

5. Shared filters

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.

ParameterMeaning
addressFull recipient address, e.g. qa.signup@inboxlumo.com.
domainRestrict results to one domain.
fromA 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.
subjectCase-insensitive substring match against the subject line.
qCase-insensitive substring search over the subject, sender address, sender name and recipient.
sinceISO 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.
limitPage size, up to 100. Defaults to 50. Listing only.
cursorPass 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']}")

Step-by-step test files for Playwright and Cypress, including magic links and parallel runs: How to test email OTP in Playwright and Cypress.

Create the address once, reuse it

Run this once to get the address for FDM_ADDRESS. Old mail never confuses a run because each run filters with since.

bash
curl -s -X POST https://freedomainmail.com/api/v1/addresses \
  -H "Authorization: Bearer $FDM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "inboxlumo.com", "name": "ci.signup"}' | grep -o '"address":"[^"]*"'

export FDM_ADDRESS="ci.signup@inboxlumo.com"

7. Limits

  • 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 429 rate_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.

8. Errors

Every error response has the same JSON shape:

{
  "error": {
    "code": "not_found",
    "message": "No matching message."
  }
}
HTTPCodeMeaning / what to do
401unauthorizedMissing, malformed, or revoked API key. Check the Authorization header.
404not_foundNo matching message, or a wait timed out, or the address is not yours. Retry or check the address.
400invalid_requestA parameter is missing or malformed (e.g. no address, bad since, bad pattern).
429rate_limitedToo many requests; see Retry-After.
429too_many_waitsToo many concurrent wait requests for this key.
409 / 400 / 429name_taken, name_busy, name_invalid, limit_reached, daily_limitCreating an address only — see POST /addresses.
500internal_errorSomething went wrong on our end. Safe to retry.

9. FAQ

Why does /code return 404?

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.