Getting started

Register an address and read your first message.

Before your first request

Send the key as Authorization: Bearer <key>. Keep it in a safe place.

Read your first message

BASE=https://api.fabricatedemail.com
KEY=$FABRICATEDEMAIL_KEY

# 1. Register a random address, and print the answer — see "Sharing email
#    addresses" below.
ADDRESS="run-$(openssl rand -hex 8)@fabricatedemail.com"
ANSWER=$(curl -sS -X POST "$BASE/subscriptions" \
  -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d "{\"address\":\"$ADDRESS\",\"ttlSeconds\":3600}")
echo "$ANSWER"
SID=$(echo "$ANSWER" | sed -n 's/.*"id":"\([^"]*\)".*/\1/p')

# 2. Have the system under test send mail to $ADDRESS.

# 3. Wait for it. The request holds open for up to 30 seconds.
curl -sS "$BASE/subscriptions/$SID/messages?wait=30" \
  -H "Authorization: Bearer $KEY"

# 4. Delete the address. A live address counts against your account's cap.
curl -sS -X DELETE "$BASE/subscriptions/$SID" \
  -H "Authorization: Bearer $KEY"

The long poll returns as soon as a message lands to us. The full request and response shapes are in the HTTP API contract and the API reference.

Sharing email addresses

Two jobs that pick the same local part do not share a mailbox. If the jobs share an API key the second registration will delete the first subscription and its stored messages, and returns 201 with a new id. The first job's id then returns 404. Mail meant for the first job could in this case arrive in the second job's mailbox. If they do not share an API key the second will get a 409 {"error": "address is registered by another key"} upon registration attempt.

SPF, DKIM, DMARC and blocked domains

Our Email Routing rejects inbound mail that fails both SPF and DKIM, mail that fails the sending domain's DMARC policy, and mail from blocklisted IP addresses and domains. This is a security precaution and protects us from misuse. Those emails are rejected before our service sees them, so nothing shows up in the API.

Where to go next

• Why mail might not arrive — every silent failure mode, in the order worth checking.
• HTTP API contract — every endpoint, status code, limit and assertion recipe. Self-contained.
• API reference — the same surface generated from the OpenAPI document.
• Emails containing codes and links — pull a verification code out of a message without writing a regular expression.
• MCP server — the same tools for a coding agent.
• Stability policy — what we may change under a working client, and what we may not.
• Pricing — the tiers and their caps.