Developers

Temp Mail API

Borrow disposable inboxes from your tests and scripts. One request creates a temp mail address; another waits for the email and hands you the verification code. Free, no sign-up, no API key.

The basics

Base URL: https://tempmail.loan/api/v1
No API key. Creating an inbox returns a token; send it as Authorization: Bearer <token> on every other request. It is shown only once, so keep it.
Every response is JSON shaped as { ok: true, data } or { ok: false, error: { code, message } }, with a matching HTTP status.
All timestamps are Unix epoch milliseconds.

Endpoints

Create an inbox

POST/api/v1/mailboxes

Borrows a new random temp mail address for 24 hours. No request body.

Request

curl -X POST https://tempmail.loan/api/v1/mailboxes

Response

{
  "ok": true,
  "data": {
    "address": "quietfox4821@tempmail.loan",
    "token": "tm_7rQ…",
    "createdAt": 1792335600000,
    "expiresAt": 1792422000000
  }
}

List messages

GET/api/v1/messages?since=&wait=

Returns up to 50 messages, newest first. Full bodies are left out; fetch a single message to read it.

since — only messages received after this timestamp (ms). Pass the newest receivedAt you have seen.
wait — seconds to hold the request open (0–30) when there is nothing new yet. Returns as soon as mail arrives.

Request

curl "https://tempmail.loan/api/v1/messages?wait=30" \
  -H "Authorization: Bearer <token>"

Response

{
  "ok": true,
  "data": {
    "messages": [
      {
        "id": "4b1f0c7e-…",
        "from": { "address": "no-reply@example.com", "name": "Example" },
        "subject": "Your verification code",
        "preview": "Use 482913 to finish signing up…",
        "code": "482913",
        "receivedAt": 1792335642000,
        "readAt": null
      }
    ]
  }
}

Read a message

GET/api/v1/messages/{id}

Returns the summary fields plus to, text and html (either can be null), and marks the message as read.

Request

curl https://tempmail.loan/api/v1/messages/<id> \
  -H "Authorization: Bearer <token>"

Delete a message

DELETE/api/v1/messages/{id}

Removes one message from the inbox. Returns data: null.

Get the inbox

GET/api/v1/mailbox

Returns the address and timestamps for the token, or 404 once it has expired.

Return the inbox early

DELETE/api/v1/mailbox

Deletes the address and all of its mail right away. The token stops working.

Example: wait for a verification code

Python standard library only. Create an inbox, use the address in your sign-up flow, then long-poll until the code arrives.

Python

import json
import urllib.request

BASE = "https://tempmail.loan/api/v1"


def call(path, method="GET", token=None):
    request = urllib.request.Request(BASE + path, method=method)
    if token:
        request.add_header("Authorization", f"Bearer {token}")
    with urllib.request.urlopen(request, timeout=40) as response:
        body = json.load(response)
    if not body["ok"]:
        raise RuntimeError(body["error"]["code"])
    return body["data"]


inbox = call("/mailboxes", method="POST")
print("Sign up with:", inbox["address"])

# Long-poll until the verification email shows up
while True:
    messages = call("/messages?wait=30", token=inbox["token"])["messages"]
    if messages:
        print("Code:", messages[0]["code"])
        break

The code field is a best-effort guess and can be null; fall back to parsing text for unusual email templates.

Errors

Error response

{
  "ok": false,
  "error": {
    "code": "TEMPMAIL.MAILBOX_NOT_FOUND",
    "message": "This mailbox has expired or does not exist"
  }
}

Status	Code	Meaning
400	COMMON.BAD_REQUEST	A query parameter is invalid.
401	COMMON.UNAUTHORIZED	The Authorization header is missing.
404	TEMPMAIL.MAILBOX_NOT_FOUND	The token is unknown or the inbox has expired. Create a new one.
404	TEMPMAIL.MESSAGE_NOT_FOUND	No message with that id in this inbox.
429	TEMPMAIL.RATE_LIMITED	Too many requests from your IP. Back off and retry.

Limits

Inbox lifetime: 24 hours, then deleted with all of its mail
Inboxes created: 10 per minute per IP
Read requests: 120 per minute per IP
Long-poll wait: Up to 30 seconds per request
Messages per inbox: 50 — further mail is rejected
Message size: 5 MB — larger mail is rejected
Sending: Not supported — inboxes are receive-only