Open API
Create temporary inboxes and read emails with a simple HTTP API, ideal for automated tests and sign-up flow verification. All endpoints return JSON.
Authentication
Creating a mailbox returns a token. Send it on subsequent requests:
Authorization: Bearer <token>
Rate limits
Without an API key, each IP can create up to 10 mailboxes per minute. For higher limits, send an API key when creating mailboxes:
X-API-Key: tm_xxxxxxxxxxxxxxxx
Endpoints
| Method | Path | Description |
|---|---|---|
| GET | /api/domains | List available domains |
| POST | /api/mailbox | Create a mailbox. Empty body for a random address, or {"local":"abc","domain":"…"} for a custom one |
| GET | /api/mailbox | Current mailbox info |
| DELETE | /api/mailbox | Delete the mailbox and all its emails |
| GET | /api/messages | List inbox (latest 100) |
| GET | /api/messages/{id} | Get an email (body and attachment list) |
| DELETE | /api/messages/{id} | Delete an email |
| GET | /api/messages/{id}/raw | Download the raw .eml |
| GET | /api/attachments/{id} | Download an attachment |
| GET | /api/events | SSE event stream, pushes event: mail on new emails |
Examples
# 1. Create a mailbox. Empty body for a random address, or {"local":"abc","domain":"…"} for a custom one
curl -s -X POST https://www.temp-mail.cc/api/mailbox \
-H 'Content-Type: application/json' -d '{}'
# => {"address":"[email protected]","token":"…","expires_at":"…"}
# 2. List inbox (latest 100)
curl -s https://www.temp-mail.cc/api/messages \
-H 'Authorization: Bearer <token>'
# 3. Get an email (body and attachment list)
curl -s https://www.temp-mail.cc/api/messages/123 \
-H 'Authorization: Bearer <token>'
# Python
import requests, time
base = "https://www.temp-mail.cc"
mb = requests.post(f"{base}/api/mailbox", json={}).json()
headers = {"Authorization": f"Bearer {mb['token']}"}
print(mb["address"])
while True:
msgs = requests.get(f"{base}/api/messages", headers=headers).json()["messages"]
if msgs:
print(requests.get(f"{base}/api/messages/{msgs[0]['id']}", headers=headers).json()["text"])
break
time.sleep(3)
Errors
On error a non-2xx status is returned with a JSON body:
{"error": "rate_limited", "message": "…"}