Developer API

Build with the TryTempInbox API

Programmatically generate disposable email addresses, poll the inbox and read or delete messages. Free and CORS-enabled — sign in with GitHub to get your API key, then call the API from your browser, backend or test suite.

Base URL

https://tempinbox-api.tempmail-imad.workers.dev

Authentication

Required for programmatic access — send your key as X-API-Key: YOUR_API_KEY. Sign in with GitHub to get yours — one unique key per GitHub account. (Only this website's own pages may call the API keyless.)

Format

JSON in, JSON out. Every response includes anti-caching headers so you always see a live inbox.

Rate limits

With your API key: 25 requests/minute and 1,000 requests/24 hours per key. Details →

Get your API key

Keys are minted exclusively through GitHub sign-in — one unique key per GitHub account — with 25 requests/minute and 1,000 requests/day included free. There is no other way to get a key: developers who don't sign in with GitHub simply don't get one.

One click — no passwords, no forms. We only read your public GitHub profile.
Your key pops up right here after sign-in — copy it and keep it somewhere safe.
Lost it? Signing in again with the same GitHub account always returns the same key.

Sign in with GitHub

You'll hop to GitHub and straight back — your key appears in a popup on this page.

Quickstart

The whole workflow in four steps: generate an address → check the inbox → read a message → delete it. Pick your language — every block is self-contained and copy-paste ready. Every request sends your key as the X-API-Key header — replace YOUR_API_KEY with the key you got from signing in.

cURL Terminal

# 0. Sign in with GitHub (see "Get your API key" above) and export your key —
#    it is sent on every request as the X-API-Key header.
API_KEY="YOUR_API_KEY"

# 1. Generate a new temporary address (valid for 10 minutes)
curl -s -X POST https://tempinbox-api.tempmail-imad.workers.dev/api/addresses \
  -H "X-API-Key: $API_KEY"
# → {"address":"gsi3bo@trytempinbox.com","token":"gsi3bo~9b1deb4d-…","expiresAt":1786294800000}
#   Copy the "token" value — it authorizes every inbox call below.

# 2. Check the inbox (returns an array of messages, newest first)
curl -s -H "X-API-Key: $API_KEY" \
  "https://tempinbox-api.tempmail-imad.workers.dev/api/addresses/YOUR_TOKEN/messages"

# 3. Read a message — bodies are already included in the inbox payload,
#    so the same call doubles as the "read message" endpoint.

# 4. Delete a message by id
curl -s -X DELETE -H "X-API-Key: $API_KEY" \
  "https://tempinbox-api.tempmail-imad.workers.dev/api/addresses/YOUR_TOKEN/messages/MESSAGE_ID"

JS JavaScript (Node 18+ / browser — save as .mjs)

const API = 'https://tempinbox-api.tempmail-imad.workers.dev';
const API_KEY = 'YOUR_API_KEY'; // sign in with GitHub to get yours
const headers = { 'X-API-Key': API_KEY };

// 1. Generate a new temporary address (valid for 10 minutes)
const res = await fetch(`${API}/api/addresses`, { method: 'POST', headers });
const { address, token, expiresAt } = await res.json();
console.log('Your temporary address:', address);

// 2. Check the inbox (returns an array of messages, newest first)
const messages = await (await fetch(`${API}/api/addresses/${token}/messages`, { headers })).json();

// 3. Read the first message — bodies are included in the inbox payload
if (messages.length) {
    const first = messages[0];
    console.log(first.subject, first.bodyText || first.bodyHtml);

    // 4. Delete it
    await fetch(`${API}/api/addresses/${token}/messages/${first.id}`, { method: 'DELETE', headers });
}

PY Python (requires `pip install requests`)

import requests

API = "https://tempinbox-api.tempmail-imad.workers.dev"
HEADERS = {"X-API-Key": "YOUR_API_KEY"}  # sign in with GitHub to get yours

# 1. Generate a new temporary address (valid for 10 minutes)
session = requests.post(f"{API}/api/addresses", headers=HEADERS).json()
address, token = session["address"], session["token"]
print("Your temporary address:", address)

# 2. Check the inbox (returns a list of messages, newest first)
messages = requests.get(f"{API}/api/addresses/{token}/messages", headers=HEADERS).json()

# 3. Read the first message — bodies are included in the inbox payload
if messages:
    first = messages[0]
    print(first["subject"], first["bodyText"] or first["bodyHtml"])

    # 4. Delete it
    requests.delete(f"{API}/api/addresses/{token}/messages/{first['id']}", headers=HEADERS)

Endpoint reference

All paths are relative to the base URL, and every request carries your key as X-API-Key: YOUR_API_KEY. Session tokens have the form {localPart}~{uuid} — the local part is embedded so requests can be routed, and the uuid half is the secret that authorizes them.

POST /api/addresses

Generate a temporary email address

Claims a random address for a 10-minute session. No request body required. Responds 201 Created:

{
  "address": "gsi3bo@trytempinbox.com",
  "token": "gsi3bo~9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "expiresAt": 1786294800000
}

expiresAt is a Unix millisecond timestamp. Mail sent to the address appears in the inbox until that moment — then everything is wiped automatically.

GET /api/addresses/{token}

Resolve a session token

Turns a token back into its address and expiry — handy when a session was shared to another device (e.g. via QR code). Responds 200 OK:

{
  "address": "gsi3bo@trytempinbox.com",
  "expiresAt": 1786294800000
}

GET /api/addresses/{token}/messages

Check the inbox & read messages

Returns every message in the inbox, newest first. Reads are strongly consistent — mail is visible on the first poll after it lands, so polling every few seconds is enough. Full plain-text and HTML bodies are included inline, so this doubles as the "read message" endpoint. Responds 200 OK:

[
  {
    "id": "b3f1c2a4-1e5d-4c8a-9f2e-7c6d5b4a3928",
    "from": "no-reply@example.com",
    "subject": "Your verification code",
    "bodyText": "Your code is 123456",
    "bodyHtml": "Your code is 123456",
    "receivedAt": 1786294213000
  }
]

An empty inbox returns []. Always render bodyHtml inside a sandboxed frame or sanitized — it is raw sender-supplied HTML.

GET /api/inbox?address={address}&token={token}

Check the inbox (address-keyed alias)

Identical payload to the messages endpoint above, but keyed by query parameters instead of the path. The token is still required and verified — knowing the address alone grants nothing.

curl -s -H "X-API-Key: YOUR_API_KEY" \
  "https://tempinbox-api.tempmail-imad.workers.dev/api/inbox?address=gsi3bo@trytempinbox.com&token=gsi3bo~9b1deb4d-…"

DELETE /api/addresses/{token}/messages/{id}

Delete a message

Permanently removes one message from the inbox. Responds 200 OK:

{
  "success": true,
  "id": "b3f1c2a4-1e5d-4c8a-9f2e-7c6d5b4a3928"
}

Error responses

Errors are always JSON with an error field, and always carry CORS headers so browser clients can read them.

Status	When	Example body
401	No API key sent (required for programmatic access), or the key you sent doesn't exist / was revoked. Sign in with GitHub to get or retrieve your key.	{ "error": "Unauthorized", … }
404	Invalid/expired token, unknown message id, or unknown route.	{ "error": "Invalid or expired token" }
429	Rate limit exceeded (see policies). Includes a `Retry-After` header.	{ "error": "Too Many Requests", … }
500	Unexpected server error — safe to retry with backoff.	{ "error": "Internal server error" }

HTTP/1.1 429 Too Many Requests
Retry-After: 60

{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded: your quota allows 25 requests per minute. Please retry later. Need higher limits? Contact api@trytempinbox.com.",
  "limit": "25 requests per minute",
  "retryAfter": 60,
  "contact": "api@trytempinbox.com"
}

API policies

CORS enabled

Every response — including errors — sends Access-Control-Allow-Origin: * with GET, POST, DELETE, OPTIONS allowed. Call the API directly from browser apps, Node, Python, or anywhere else — no proxy needed.

Automatic deletion

Inboxes live for 10 minutes from creation (see expiresAt), then a storage alarm wipes the address, token and every message — nothing is retained. Inboxes hold at most 100 messages, and message bodies are truncated at 100,000 characters.

Rate limits

With an API key (GitHub sign-in): 25 requests per minute and 1,000 requests per 24 hours — verified against the key's record on every request. Keyless access is reserved for this website's own pages (per-IP pool of 120/minute, 5,000/day); any other client without a valid key gets 401. Exceeding a limit returns 429 Too Many Requests with a JSON explanation and a Retry-After header.

Need higher limits?

Building something bigger — an automated test suite, a CI integration, a product on top of disposable inboxes? Email api@trytempinbox.com with your API key, a sentence about your use case and your expected volume — quotas are per key, so raising yours takes minutes.

Fair use applies: don't use the API to send spam, abuse third-party services, or violate the Terms of Service.

Build with the TryTempInbox API

Base URL

Authentication

Format

Rate limits

Get your API key

Quickstart

cURL Terminal

JS JavaScript (Node 18+ / browser — save as .mjs)

PY Python (requires pip install requests)

Endpoint reference

Generate a temporary email address

Resolve a session token

Check the inbox & read messages

Check the inbox (address-keyed alias)

Delete a message

Error responses

API policies

CORS enabled

Automatic deletion

Rate limits

Need higher limits?

PY Python (requires `pip install requests`)