Endpoints

All endpoints return JSON and set Cache-Control: no-store.

`GET /api/tempmail/domains`

Returns supported mail domains and random alias algorithms.

{
  "domains": ["fuckemail.org", "g3m4.dev", "shineshop.store", "freelet.org"],
  "default_domain": "fuckemail.org",
  "random_algorithms": ["word-word-number", "word-number", "person-name", "person-number", "initials-number", "readable-short", "compact", "hex"],
  "retention_seconds": 86400,
  "max_visible_messages_per_alias": 50,
  "poll_interval_seconds": 10
}

`POST /api/tempmail/address`

Creates or claims an address for the current API session. If no session exists, the response sets tm_session and tm_nonce cookies.

Random address body

{
  "random": true,
  "domain": "g3m4.dev",
  "algorithm": "compact"
}

Explicit address body

{
  "email": "blue-river-4821@g3m4.dev"
}

or:

{
  "alias": "blue-river-4821",
  "domain": "g3m4.dev"
}

Response

{
  "email": "abc123def4@g3m4.dev",
  "alias": "abc123def4",
  "domain": "g3m4.dev",
  "messages": []
}

Aliases must be 3-32 lowercase letters, numbers, dots, dashes, or underscores. Leading/trailing dots, double dots, plus addressing, and unsupported domains are rejected.

`GET /api/tempmail/inbox?email=:email`

Lists messages visible to the current API session for a claimed address.

Required header:

Cookie: tm_session=...; tm_nonce=...

Response:

{
  "email": "abc123def4@g3m4.dev",
  "messages": [
    {
      "id": "message-id",
      "sender_name": "Sender",
      "sender_email": "sender@example.com",
      "subject": "Welcome code",
      "preview": "Your verification code is 123456.",
      "received_at": 1760000000000,
      "attachment_count": 0,
      "otp_code": "123456"
    }
  ]
}

`GET /api/tempmail/messages/:id`

Returns full detail for a message visible to the current API session.

Response fields include:

id
recipient
sender_name
sender_email
subject
preview
text_body
sanitized_html_body
received_at
expires_at
attachment_count
parse_status

HTML is sanitized before storage and unsafe scripts/events/JavaScript links are stripped.

`DELETE /api/tempmail/inbox?email=:email`

Clears the inbox only for the current API session. Other sessions that claimed the same temp address can still see their own visible messages.

Response:

{ "ok": true }

Errors

Errors use a stable error string:

{ "error": "session_required" }

Common statuses:

400 — email_required, invalid_address, or message_id_required
401 — session_required
404 — not_found
429 — rate_limited