Introduction

All API endpoints accept and return JSON. Base URL is the deployment origin (https://mail.hyproxy.lol).

Every request that reads messages or manages inboxes must carry a valid X-API-Key header. The master key (set as a secret) authenticates as "master"; created keys authenticate as their own raw value and inherit a 1-year TTL.

Mail addresses follow the pattern <local>@hyproxy.lol. Temporary addresses (any random recipient that receives mail) are stored for 24 hours. Registered addresses created via the Inbox Manager are stored for 7 days and can be re-claimed by exactly one API key at a time.

Authentication

Pass your API key in the X-API-Key header (or as ?key= query param).

The master key is configured as a worker secret at deploy time. Created keys live in the apikey:<key> KV records and can be revoked from the admin panel.

curl -H "X-API-Key: YOUR_KEY" \
  "https://mail.hyproxy.lol/messages?to=solar.onyx.3168@hyproxy.lol"

# Alternative: query string parameter
curl "https://mail.hyproxy.lol/messages?to=solar.onyx.3168@hyproxy.lol&key=YOUR_KEY"

Rate Limits

Address creation (POST /api/inboxes) is rate-limited per API key.

Two layers enforce the limit: an in-isolate memory counter (strict) and a cross-isolate KV epoch counter (best-effort). The strict per-isolate layer means bursts within a single Worker isolate will always return 429.

Message reads (/messages, /code) are not rate-limited.

Get Messages

List messages stored for a recipient address, newest first. Max 50 results.

curl -H "X-API-Key: YOUR_KEY" \
  "https://mail.hyproxy.lol/messages?to=solar.onyx.3168@hyproxy.lol"

{
  "messages": [
    {
      "from": "verify@accounts.google.com",
      "subject": "Your verification code",
      "ts": 1715000000000,
      "text": "Your Google verification code is 482913. ..."
    }
  ]
}

Get Verification Code

Extract a numeric verification code from the latest message stored for an address.

The regex (?<!\d)(\d{n})(?!\d) is run over the concatenation of the latest message's subject and body. Returns null if no code is found.

curl -H "X-API-Key: YOUR_KEY" \
  "https://mail.hyproxy.lol/code?to=solar.onyx.3168@hyproxy.lol&digits=6"

{
  "code": "482913",
  "ts": 1715000000000,
  "from": "verify@accounts.google.com",
  "subject": "Your verification code"
}

Create Inbox

Create a permanent address (7-day message retention, no TTL on the slot itself).

Send either { "random": true } for an adjective.noun.4digits name (e.g. solar.onyx.3168), or { "name": "my-inbox" } with a custom 3–30 char local part.

# Random
curl -X POST -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"random":true}' \
  "https://mail.hyproxy.lol/api/inboxes"

# Custom
curl -X POST -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"name":"signup-flow"}' \
  "https://mail.hyproxy.lol/api/inboxes"

{
  "addr": "solar.onyx.3168@hyproxy.lol",
  "created": 1715000000000
}

List Inboxes

List all permanent inboxes owned by the current API key. Includes message count per inbox.

curl -H "X-API-Key: YOUR_KEY" \
  "https://mail.hyproxy.lol/api/inboxes"

{
  "inboxes": [
    { "addr": "solar.onyx.3168@hyproxy.lol", "created": 1715000000000, "messages": 3 },
    { "addr": "signup-flow@hyproxy.lol", "created": 1714999999000, "messages": 0 }
  ],
  "used": 2,
  "max": 25
}

Inbox Messages

Fetch messages and the extracted 6-digit code for an inbox you own.

Returns 403 if the inbox is not owned by your key. Includes a pre-extracted code field for the latest message.

curl -H "X-API-Key: YOUR_KEY" \
  "https://mail.hyproxy.lol/api/inboxes/messages?addr=solar.onyx.3168@hyproxy.lol"

{
  "messages": [
    { "from": "no-reply@example.com", "subject": "Code", "ts": 1715000000000, "text": "Your code: 482913" }
  ],
  "code": "482913"
}

Delete Inbox

Release a permanent inbox slot. The reg: and inbox: records are deleted immediately; the address becomes claimable again.

Returns 403 if the inbox is not owned by your key.

curl -X DELETE -H "X-API-Key: YOUR_KEY" \
  "https://mail.hyproxy.lol/api/inboxes?addr=solar.onyx.3168@hyproxy.lol"

{ "ok": true, "addr": "solar.onyx.3168@hyproxy.lol" }

Errors

All errors return JSON with error and message fields.