The API

Quickstart

Create an address, then poll it for mail. Two calls, no setup.

# 1. take an address — the token comes back once, keep it
curl -X POST https://weirdlytemp.sbs/v1/inboxes

{
  "address": "brisk-harbor-4821@weirdlytemp.sbs",
  "token": "H8sQ...",
  "created_at": 1785816262,
  "expires_at": 1785819862
}

# 2. read the mail
curl https://weirdlytemp.sbs/v1/inboxes/brisk-harbor-4821@weirdlytemp.sbs/messages \
  -H "Authorization: Bearer H8sQ..."

Authentication

Two independent credentials, used for different things.

The inbox token is returned once when you create an inbox and is required to read or delete its mail. Only a hash of it is stored, so a lost token cannot be recovered — create a new inbox instead. Send it as Authorization: Bearer <token>.

An API key is optional and identifies you for rate limiting only. It grants no access to anyone else's mail. Send it as X-API-Key: wt_.... Create one on the account page.

Creates an inbox. Every field is optional; an empty body gives you a random address.

curl -X POST https://weirdlytemp.sbs/v1/inboxes \
  -H "Content-Type: application/json" \
  -d '{"local_part": "my-signup", "ttl_seconds": 7200}'

Metadata for an inbox you hold the token for.

{
  "address": "my-signup@weirdlytemp.sbs",
  "created_at": 1785816262,
  "expires_at": 1785823462,
  "message_count": 2
}

Destroys the inbox and every message in it immediately. Returns 204.

Lists messages, newest first. Bodies are omitted — fetch a single message for those.

{
  "address": "my-signup@weirdlytemp.sbs",
  "expires_at": 1785823462,
  "messages": [
    {
      "id": "0f2c8e1a-...",
      "from_addr": "noreply@github.com",
      "from_name": "GitHub",
      "subject": "Your verification code",
      "size": 4821,
      "truncated": 0,
      "seen": 0,
      "received_at": 1785816302
    }
  ]
}

The full message, adding text_body and html_body. Reading marks it seen.

Deletes one message. Returns 204, or 404 if it isn't there.

Service endpoints

Limits

An API key raises the per-IP limits above.

Address names

A name is 1 to 64 characters of a-z, 0-9, ., -, _ and +, and cannot start or end with a dot. Names are lowercased.

Eleven names are refused: admin, administrator, webmaster, hostmaster, postmaster, abuse, security, root, sysadmin, ssladmin and ssl-admin. A certificate authority will issue a TLS certificate for a domain to whoever receives mail at the first five, so they cannot be handed out.

Note that signup forms elsewhere often validate email more strictly than this API does, so an address accepted here may still be rejected there.

Errors

Every error is JSON of the shape {"error": "..."}.