🛠️ Developers

Temporary Email API

Generate a disposable inbox, receive emails and read them — over a simple REST API. 100% free, no API key or sign-up required.

⚠️ Public inbox. Anyone who knows an address can read its messages — that's how disposable email works. Use it for sign-up codes and avoiding spam, never for banking or sensitive accounts. Messages auto-delete after 24 hours.

Base URL

All requests go to the API base URL. No authentication header is needed (an optional API key is supported).

# Base URL https://grabcast-api-342720596878.us-central1.run.app

Quick start

Create an address, then poll its inbox and read a message:

# 1) Generate a fresh disposable address curl -X POST https://grabcast-api-342720596878.us-central1.run.app/api/tmpmail/new \ -H "Content-Type: application/json" -d '{}' # -> { "address": "coolotter8f3kx@inbox.grabcast.click", "domain": "...", "ttl_hours": 24 } # 2) Poll the inbox (repeat every ~10s) curl https://grabcast-api-342720596878.us-central1.run.app/api/tmpmail/coolotter8f3kx@inbox.grabcast.click # -> { "addr": "...", "count": 1, "messages": [{ "id": 12, "from_addr": "...", "subject": "...", "snippet": "...", "read": false, "created_at": "..." }] } # 3) Read a full message by id (marks it read) curl https://grabcast-api-342720596878.us-central1.run.app/api/tmpmail/coolotter8f3kx@inbox.grabcast.click/12

Endpoints

GET/api/tmpmail/config

Returns the available domains[] (the pool) and ttl_hours. Pick any domain from the pool for your addresses.

POST/api/tmpmail/new

Generate a random address. Optional body {"domain":"..."} to pick a pool domain (else random). Returns address, domain, ttl_hours. You can also just build your own: anything@<pool-domain> (localpart: letters/digits/._- , 1–64 chars).

GET/api/tmpmail/{address}

List messages for an address (newest first, up to 50). Each item: id, from_addr, from_name, subject, snippet, read, created_at (UTC ISO).

GET/api/tmpmail/{address}/{id}

Full message: text_body, html_body, headers. Marks it read. Render html_body in a sandboxed iframe to stay XSS-safe.

DELETE/api/tmpmail/{address}/{id}

Delete one message.

DELETE/api/tmpmail/{address}

Empty the whole inbox for an address.

Rate limits & fair use

Per-IP: /new 20/min and 120/day · reads (list & read) 120/min · deletes 60/min. Over the limit → 429 with Retry-After.
Poll every 10–15s and stop when your tab/process is idle — don't hammer the inbox.
Messages auto-expire after 24h; each address keeps at most 50 messages; attachments are dropped.
Want higher limits / a private domain? Connect your own domain (BYOD) — it gets its own quota and isn't shared. See the Temporary Email tool.

API keys (optional)

The Temp Mail API works without a key. A free personal API key is useful when a script acts on your account — e.g. syncing your saved tools — or when you want your Temp Mail traffic tied to your account. Keys never raise the per-IP limits above.

Create up to 3 keys on your account page. Each key is shown once; we store only a hash. Revoke or regenerate a key any time.
Send it only in the header X-API-Key: gc_…. Keys in the URL (e.g. ?api_key=) are rejected with 400.
Permissions (scopes) you pick per key:
- account:read — GET /api/auth/me
- prefs:read — GET /api/me/prefs · prefs:write — PUT /api/me/prefs
- tmpmail:read — GET /api/tmpmail/config, /locked/{address}, /{address}, /{address}/{id}
- tmpmail:write — POST /api/tmpmail/new, POST /api/tmpmail/lock, DELETE /api/tmpmail/{address}[/{id}]
Everything else refuses keys (403 api_key_not_allowed): password, sessions, key management, data export, account deletion, AI keys, admin, social publishing and the AI endpoint.
Fair use per key: 60 requests/minute and 3,000/day; per account (all keys together): 120/minute and 6,000/day. Responses carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (unix time); over the limit you get 429 with Retry-After.

# Read your synced favorites with a key that has prefs:read curl https://grabcast-api-342720596878.us-central1.run.app/api/me/prefs -H "X-API-Key: $GRABCAST_API_KEY"

Key errors use one JSON shape: {"detail": "message", "error": {"code": "…", "message": "…"}}.

401 api_key_invalid — unknown, malformed or revoked key.
403 insufficient_scope — the key lacks the permission (error.required_scope names it).
403 api_key_not_allowed — the endpoint can't be called with a key.
403 account_locked · 400 api_key_in_query · 429 rate_limited.

Notes

Receive-only — a disposable inbox cannot send email.
Addresses are namespaced by domain; the same localpart on two different pool domains are two separate inboxes.
CORS is open, so you can call the API directly from the browser.

Try the Temporary Email tool →