API reference

Common endpoints. See https://api.tempfoxmail.com/docs for the full OpenAPI schema.

Create an inbox

POST /v1/inboxes — optional Bearer API key. A webhook_url requires a Bearer key.

curl -X POST https://api.tempfoxmail.com/v1/inboxes \
  -H "Authorization: Bearer tfm_live_…" \
  -H "content-type: application/json" \
  -d '{ "domain": "example.com" }'

The response is the only place the capability_token and webhook secret are ever returned:

{
  "id": "…",
  "address": "[email protected]",
  "capability_token": "…",
  "expires_at": "2026-01-01T12:00:00Z",
  "max_expires_at": "2026-01-02T12:00:00Z",
  "webhook": null
}

List messages

GET /v1/inboxes/{inbox_id}/messages — returns lightweight previews, newest first.

curl https://api.tempfoxmail.com/v1/inboxes/$INBOX_ID/messages \
  -H "X-Inbox-Token: $TOKEN"

Get a message

GET /v1/messages/{message_id} — full detail with sanitized HTML and headers.

curl https://api.tempfoxmail.com/v1/messages/$MSG_ID -H "X-Inbox-Token: $TOKEN"

Get the one-time passcode

GET /v1/messages/{message_id}/otp — extracted OTP and links, if any.

{ "otp": "123456", "links": ["https://example.com/verify?…"] }

WebSocket

Real-time delivery uses a short-lived ticket. POST /v1/ws-ticket (inbox token) returns a ticket and a ws_url; connect to it and receive message.received and inbox.closed events. The ticket travels in the query string, so the WebSocket URL is never logged.

const { ws_url } = await (await fetch("https://api.tempfoxmail.com/v1/ws-ticket", {
  method: "POST",
  headers: { "X-Inbox-Token": token, "content-type": "application/json" },
  body: "{}",
})).json();

const ws = new WebSocket(ws_url);
ws.onmessage = (e) => console.log(JSON.parse(e.data));

Account endpoints (registered users)

These require a session cookie (web sign-in):