Developer API

Build with the TryTempInbox API

Programmatically generate disposable email addresses, poll the inbox and read or delete messages. Free, keyless and CORS-enabled — straight from your browser, backend or test suite.

Base URL

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

Authentication

No API key. The session token returned when you create an address is the only credential — keep it secret.

Format

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

Rate limits

20 requests/minute and 400 requests/24 hours per IP address. Details →

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.

cURL Terminal 

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

# 2. Check the inbox (returns an array of messages, newest first)
curl -s "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 "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';

// 1. Generate a new temporary address (valid for 10 minutes)
const res = await fetch(`${API}/api/addresses`, { method: 'POST' });
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`)).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' });
}

PY Python (requires pip install requests) 

import requests

API = "https://tempinbox-api.tempmail-imad.workers.dev"

# 1. Generate a new temporary address (valid for 10 minutes)
session = requests.post(f"{API}/api/addresses").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").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']}")

Endpoint reference

All paths are relative to the base URL. 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 "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
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: each IP address may make 20 requests per minute. Please retry later. Need higher limits? Contact api@trytempinbox.com.",
  "limit": "20 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

Enforced per client IP address: 20 requests per minute and 400 requests per 24 hours. Exceeding either 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 a sentence about your use case and expected volume, and we'll raise your quota.

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