Developers

API v1

REST + JSON. Long-poll waiting, webhook pushes, automatic verification-code extraction. Create keys in your dashboard.

Authentication

Send your key in the X-Api-Key header. Keys are stored hashed; the dashboard shows only a prefix. Sandbox keys (tmp_test_…) can seed fake mail via POST /v1/sandbox/deliver.

curl -s https://your-domain/api/v1/me -H "X-Api-Key: tmp_live_…"

The 3-call signup flow (Recipe A)

# 1. create a mailbox
curl -X POST https://your-domain/api/v1/mailboxes \
  -H "X-Api-Key: $KEY" -H "Idempotency-Key: $(uuidgen)" \
  -d '{"domain":"thefatburnshift.online"}'

# 2. wait for the verification mail (blocks up to 45s)
curl -s "https://your-domain/api/v1/mailboxes/u9x2k@example.com/messages/wait?timeout=45&match=github" \
  -H "X-Api-Key: $KEY"

# 3. the response contains codes: ["482913"] — type it into the signup form. Done.

Endpoints

GET/v1/meany

Key info, plan, live limits and usage — use it for backoff.

GET/v1/domainsdomains:read

Domains pickable by your tier. Premium domains included only for pro.

GET/v1/domains/{name}/availability?local_part=domains:read

Check whether a username is free; suggests an alternative when taken.

POST/v1/mailboxesmailboxes:write

Create a mailbox: {domain?, local_part?, password?}. 409 when taken. Idempotency-Key supported.

POST/v1/mailbox-authnone

Address + mailbox password → a 1-hour read-only token. No API key needed — see "Read a mailbox with just its password".

GET/v1/mailboxesmailboxes:read

List your mailboxes (cursor pagination: ?limit=&cursor=).

GET/v1/mailboxes/{address}mailboxes:read

Mailbox details with message and unread counts.

PATCH/v1/mailboxes/{address}mailboxes:write

{password?} · {extend:true} · {recovery_email?}.

DELETE/v1/mailboxes/{address}mailboxes:write

Delete the mailbox and every message in it.

POST/v1/mailboxes/bulkbulk:write

Pro only. {count ≤50, domain?, prefix?} → 207 with per-item failures.

GET/v1/mailboxes/{address}/messagesmessages:read

List messages: ?since= ?unread=true ?limit= ?cursor=.

GET/v1/mailboxes/{address}/messages/waitmessages:read

Long-poll up to ?timeout= (30s free / 60s pro), optional ?match= substring. 204 on timeout.

GET/v1/messages/{id}messages:read

Full message incl. text, codes[], links[], attachments[].

PATCH/v1/messages/{id}messages:read

{is_read: true|false}.

DELETE/v1/messages/{id}messages:delete

Delete a message.

GET/v1/messages/{id}/sourcemessages:read

Original .eml download.

POST/v1/webhookswebhooks:write

Subscribe: {url, events[], secret?}. Secret auto-generated, shown once.

GET/v1/webhookswebhooks:write

List your webhooks with delivery health.

POST/v1/webhooks/{id}/testwebhooks:write

Send a signed test event.

GET/v1/webhooks/{id}/deliverieswebhooks:write

Delivery log: status, attempts, next retry.

DELETE/v1/webhooks/{id}webhooks:write

Unsubscribe.

POST/v1/sandbox/delivermailboxes:write

Sandbox keys only: deliver a synthetic mail to a sandbox mailbox.

Read a mailbox with just its password (no API key)

Exchange an address + its password for a short-lived token, then read that mailbox's messages (messages, messages/wait, messages/{id}, /source, /attachments/*) with the X-Mailbox-Token header instead of the key. Tokens last 1 hour, are read-only, stop working the moment the password changes, and can't touch any other mailbox.

# 1. swap password for a token (rate-limited — 15 tries / 15 min per IP)
curl -X POST https://your-domain/api/v1/mailbox-auth \
  -d '{"address":"ramen@codetohealth.online","password":"hunter22"}'
# → {"data":{"token":"tmp_mb_…","expires_in":3600,"mailbox":{…}}}

# 2. read the inbox with the token alone
curl -s https://your-domain/api/v1/mailboxes/ramen@codetohealth.online/messages \
  -H "X-Mailbox-Token: tmp_mb_…"

Webhook signatures

Every delivery carries X-TMP-Timestamp and X-TMP-Signature. Reject timestamps older than 5 minutes.

expected = "sha256=" + HMAC_SHA256(secret, timestamp + "." + raw_body)
if !constant_time_equals(expected, header["X-TMP-Signature"]) { abort(403) }

Rate limits & errors

Free keys: 60 req/min, 10 mailboxes/hour. Pro: 600 req/min, 120/hour. Every response carries X-RateLimit-Limit / -Remaining / -Reset; 429 adds Retry-After. Errors use one envelope: {"error":{"code","message","errors"?}} — codes: bad_request · unauthorized · forbidden · not_found · conflict · validation_failed · rate_limited.