API · tempmail

All endpoints under /api/v1 require an API key (create one in the admin panel).

Send credentials via either header:

Authorization: Bearer tm_xxxxxxxx
X-API-Key: tm_xxxxxxxx

GET /api/v1/health

Returns { ok: true, ts }.

GET /api/v1/domains

Lists active domains.

curl -H "Authorization: Bearer $KEY" https://your-host/api/v1/domains

GET /api/v1/messages?address=user@example.com

Lists messages for a mailbox. Optional limit (1–200, default 50) and since (epoch ms) parameters.

curl -H "Authorization: Bearer $KEY" \
  "https://your-host/api/v1/messages?address=user@example.com&limit=20"

GET /api/v1/messages/:id

Returns full message body and attachment metadata. Accepts optional ?address=… to scope by mailbox.

GET /api/v1/messages/:id/attachments/:attId

Downloads the binary attachment.

DELETE /api/v1/messages/:id?address=…

Deletes a single message in the given mailbox.

Polling example

#!/usr/bin/env bash
ADDR="user@example.com"
SINCE=0
while true; do
  res=$(curl -sS -H "Authorization: Bearer $TM_KEY" \
    "https://your-host/api/v1/messages?address=$ADDR&since=$SINCE")
  echo "$res" | jq -r '.messages[] | "\(.received_at) \(.subject)"'
  SINCE=$(date +%s%3N)
  sleep 5
done