{"openapi":"3.0.3","info":{"title":"Tempmail API","version":"1.0.0","description":"Auth: Authorization: Bearer <mailbox token | api key tmk_...> or the tm_session cookie (browser login). Registration is invite-only."},"servers":[{"url":"https://mail.0ae.dev/api/v1"}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer"},"session":{"type":"apiKey","in":"cookie","name":"tm_session"}}},"paths":{"/health":{"get":{"summary":"Health check","parameters":[],"security":[],"responses":{"200":{"description":"OK"},"4XX":{"description":"Error: {\"error\": \"...\"}"}}}},"/domains":{"get":{"summary":"Available domains and TTL limits","parameters":[],"security":[],"responses":{"200":{"description":"OK"},"4XX":{"description":"Error: {\"error\": \"...\"}"}}}},"/mailboxes":{"post":{"summary":"Create a mailbox (returns the secret token once). Logged-in users/keys get a permanent mailbox within quota; anonymous creation only if the admin enabled it","parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"description":"string?"},"domain":{"description":"string?"},"style":{"description":"readable|random"},"ttl":{"description":"seconds 300..MAX_TTL"},"pinned":{"description":"boolean (needs pin scope)"}}}}}},"security":[],"responses":{"200":{"description":"OK"},"4XX":{"description":"Error: {\"error\": \"...\"}"}}},"get":{"summary":"List mailboxes of the API key (admin: all)","description":"Auth: api key","parameters":[],"security":[{"bearer":[]},{"session":[]}],"responses":{"200":{"description":"OK"},"4XX":{"description":"Error: {\"error\": \"...\"}"}}}},"/mailboxes/{addr}":{"get":{"summary":"Mailbox info + counters","parameters":[{"name":"addr","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearer":[]},{"session":[]}],"responses":{"200":{"description":"OK"},"4XX":{"description":"Error: {\"error\": \"...\"}"}}},"patch":{"summary":"Change TTL / pin / forwarding / blocklist","parameters":[{"name":"addr","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"ttl":{"description":"seconds from now"},"extend":{"description":"seconds added"},"pinned":{"description":"boolean (pin scope)"},"forward_to":{"description":"email|null"},"blocklist":{"description":"string[]"}}}}}},"security":[{"bearer":[]},{"session":[]}],"responses":{"200":{"description":"OK"},"4XX":{"description":"Error: {\"error\": \"...\"}"}}},"delete":{"summary":"Delete mailbox with all messages","parameters":[{"name":"addr","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearer":[]},{"session":[]}],"responses":{"200":{"description":"OK"},"4XX":{"description":"Error: {\"error\": \"...\"}"}}}},"/mailboxes/{addr}/messages":{"get":{"summary":"List messages","parameters":[{"name":"addr","in":"path","required":true,"schema":{"type":"string"}},{"name":"since","in":"query","description":"since","schema":{"type":"string"}},{"name":"from","in":"query","description":"from","schema":{"type":"string"}},{"name":"subject","in":"query","description":"subject","schema":{"type":"string"}},{"name":"q","in":"query","description":"q","schema":{"type":"string"}},{"name":"unread","in":"query","description":"unread","schema":{"type":"string"}},{"name":"limit","in":"query","description":"limit","schema":{"type":"string"}}],"security":[{"bearer":[]},{"session":[]}],"responses":{"200":{"description":"OK"},"4XX":{"description":"Error: {\"error\": \"...\"}"}}}},"/mailboxes/{addr}/messages/{id}":{"get":{"summary":"Message with text/html; marks it read (mark_read=0 to skip)","parameters":[{"name":"addr","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearer":[]},{"session":[]}],"responses":{"200":{"description":"OK"},"4XX":{"description":"Error: {\"error\": \"...\"}"}}},"patch":{"summary":"Mark read/unread","parameters":[{"name":"addr","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"read":{"description":"boolean"}}}}}},"security":[{"bearer":[]},{"session":[]}],"responses":{"200":{"description":"OK"},"4XX":{"description":"Error: {\"error\": \"...\"}"}}},"delete":{"summary":"Delete message","parameters":[{"name":"addr","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearer":[]},{"session":[]}],"responses":{"200":{"description":"OK"},"4XX":{"description":"Error: {\"error\": \"...\"}"}}}},"/mailboxes/{addr}/messages/{id}/raw":{"get":{"summary":"Raw .eml","parameters":[{"name":"addr","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearer":[]},{"session":[]}],"responses":{"200":{"description":"OK"},"4XX":{"description":"Error: {\"error\": \"...\"}"}}}},"/mailboxes/{addr}/messages/{id}/attachments/{idx}":{"get":{"summary":"Attachment bytes","parameters":[{"name":"addr","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"idx","in":"path","required":true,"schema":{"type":"integer"}}],"security":[{"bearer":[]},{"session":[]}],"responses":{"200":{"description":"OK"},"4XX":{"description":"Error: {\"error\": \"...\"}"}}}},"/mailboxes/{addr}/wait":{"get":{"summary":"Long-poll for the next matching message (200 message | 408 timeout)","parameters":[{"name":"addr","in":"path","required":true,"schema":{"type":"string"}},{"name":"timeout","in":"query","description":"timeout","schema":{"type":"string"}},{"name":"since","in":"query","description":"since","schema":{"type":"string"}},{"name":"from","in":"query","description":"from","schema":{"type":"string"}},{"name":"subject","in":"query","description":"subject","schema":{"type":"string"}}],"security":[{"bearer":[]},{"session":[]}],"responses":{"200":{"description":"OK"},"4XX":{"description":"Error: {\"error\": \"...\"}"}}}},"/mailboxes/{addr}/otp/latest":{"get":{"summary":"Latest verification code / links","parameters":[{"name":"addr","in":"path","required":true,"schema":{"type":"string"}},{"name":"from","in":"query","description":"from","schema":{"type":"string"}},{"name":"subject","in":"query","description":"subject","schema":{"type":"string"}},{"name":"since","in":"query","description":"since","schema":{"type":"string"}}],"security":[{"bearer":[]},{"session":[]}],"responses":{"200":{"description":"OK"},"4XX":{"description":"Error: {\"error\": \"...\"}"}}}},"/mailboxes/{addr}/webhooks":{"get":{"summary":"List webhooks of the mailbox","parameters":[{"name":"addr","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearer":[]},{"session":[]}],"responses":{"200":{"description":"OK"},"4XX":{"description":"Error: {\"error\": \"...\"}"}}},"post":{"summary":"Register a webhook (https only)","parameters":[{"name":"addr","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"description":"https url"},"secret":{"description":"string? (>=16 chars)"}}}}}},"security":[{"bearer":[]},{"session":[]}],"responses":{"200":{"description":"OK"},"4XX":{"description":"Error: {\"error\": \"...\"}"}}}},"/mailboxes/{addr}/webhooks/{id}":{"delete":{"summary":"Delete webhook","parameters":[{"name":"addr","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearer":[]},{"session":[]}],"responses":{"200":{"description":"OK"},"4XX":{"description":"Error: {\"error\": \"...\"}"}}}},"/webhooks":{"get":{"summary":"List key-level webhooks","description":"Auth: api key (webhooks)","parameters":[],"security":[{"bearer":[]},{"session":[]}],"responses":{"200":{"description":"OK"},"4XX":{"description":"Error: {\"error\": \"...\"}"}}},"post":{"summary":"Webhook for all mailboxes of this API key","description":"Auth: api key (webhooks)","parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"description":"https url"},"secret":{"description":"string?"}}}}}},"security":[{"bearer":[]},{"session":[]}],"responses":{"200":{"description":"OK"},"4XX":{"description":"Error: {\"error\": \"...\"}"}}}},"/webhooks/{id}":{"delete":{"summary":"Delete key-level webhook","description":"Auth: api key (webhooks)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearer":[]},{"session":[]}],"responses":{"200":{"description":"OK"},"4XX":{"description":"Error: {\"error\": \"...\"}"}}}},"/auth/register":{"post":{"summary":"Register with an invite code (invite-only); starts a session","parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"username":{"description":"3-32 chars"},"password":{"description":"10-128 chars"},"invite":{"description":"XXXX-XXXX-XXXX"}}}}}},"security":[],"responses":{"200":{"description":"OK"},"4XX":{"description":"Error: {\"error\": \"...\"}"}}}},"/auth/login":{"post":{"summary":"Log in; sets HttpOnly session cookie. Locks out after repeated failures","parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"username":{"description":"string"},"password":{"description":"string"}}}}}},"security":[],"responses":{"200":{"description":"OK"},"4XX":{"description":"Error: {\"error\": \"...\"}"}}}},"/auth/logout":{"post":{"summary":"Log out (deletes the session)","parameters":[],"security":[],"responses":{"200":{"description":"OK"},"4XX":{"description":"Error: {\"error\": \"...\"}"}}}},"/auth/me":{"get":{"summary":"Current user, usage and limits","description":"Auth: session","parameters":[],"security":[{"bearer":[]},{"session":[]}],"responses":{"200":{"description":"OK"},"4XX":{"description":"Error: {\"error\": \"...\"}"}}}},"/auth/password":{"post":{"summary":"Change password (other sessions are closed)","description":"Auth: session","parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"current":{"description":"string"},"new":{"description":"string"}}}}}},"security":[{"bearer":[]},{"session":[]}],"responses":{"200":{"description":"OK"},"4XX":{"description":"Error: {\"error\": \"...\"}"}}}},"/account/keys":{"get":{"summary":"List your API keys","description":"Auth: session","parameters":[],"security":[{"bearer":[]},{"session":[]}],"responses":{"200":{"description":"OK"},"4XX":{"description":"Error: {\"error\": \"...\"}"}}},"post":{"summary":"Create an API key scoped to your mailboxes (shown once)","description":"Auth: session","parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"description":"string"},"scopes":{"description":"mailboxes:read|mailboxes:write|webhooks"}}}}}},"security":[{"bearer":[]},{"session":[]}],"responses":{"200":{"description":"OK"},"4XX":{"description":"Error: {\"error\": \"...\"}"}}}},"/account/keys/{id}":{"delete":{"summary":"Revoke an API key","description":"Auth: session","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearer":[]},{"session":[]}],"responses":{"200":{"description":"OK"},"4XX":{"description":"Error: {\"error\": \"...\"}"}}}},"/account/webhooks":{"get":{"summary":"Webhooks for all your mailboxes","description":"Auth: session","parameters":[],"security":[{"bearer":[]},{"session":[]}],"responses":{"200":{"description":"OK"},"4XX":{"description":"Error: {\"error\": \"...\"}"}}},"post":{"summary":"Add a webhook for all your mailboxes","description":"Auth: session","parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"description":"https url"},"secret":{"description":"string?"}}}}}},"security":[{"bearer":[]},{"session":[]}],"responses":{"200":{"description":"OK"},"4XX":{"description":"Error: {\"error\": \"...\"}"}}}},"/account/webhooks/{id}":{"delete":{"summary":"Delete webhook","description":"Auth: session","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearer":[]},{"session":[]}],"responses":{"200":{"description":"OK"},"4XX":{"description":"Error: {\"error\": \"...\"}"}}}},"/account/invites":{"get":{"summary":"Your invites (when users may invite)","description":"Auth: session","parameters":[],"security":[{"bearer":[]},{"session":[]}],"responses":{"200":{"description":"OK"},"4XX":{"description":"Error: {\"error\": \"...\"}"}}},"post":{"summary":"Create a single-use invite (7 days)","description":"Auth: session","parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"note":{"description":"string?"}}}}}},"security":[{"bearer":[]},{"session":[]}],"responses":{"200":{"description":"OK"},"4XX":{"description":"Error: {\"error\": \"...\"}"}}}},"/account/invites/{id}":{"delete":{"summary":"Revoke your invite","description":"Auth: session","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearer":[]},{"session":[]}],"responses":{"200":{"description":"OK"},"4XX":{"description":"Error: {\"error\": \"...\"}"}}}},"/admin/stats":{"get":{"summary":"Counters and mail per day","description":"Auth: admin","parameters":[],"security":[{"bearer":[]},{"session":[]}],"responses":{"200":{"description":"OK"},"4XX":{"description":"Error: {\"error\": \"...\"}"}}}},"/admin/users":{"get":{"summary":"List users","description":"Auth: admin","parameters":[{"name":"q","in":"query","description":"q","schema":{"type":"string"}}],"security":[{"bearer":[]},{"session":[]}],"responses":{"200":{"description":"OK"},"4XX":{"description":"Error: {\"error\": \"...\"}"}}}},"/admin/users/{id}":{"patch":{"summary":"Block, role, quotas","description":"Auth: admin","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"blocked":{"description":"boolean"},"role":{"description":"user|admin"},"max_mailboxes":{"description":"int|null"},"max_storage":{"description":"bytes|null"},"invite_quota":{"description":"int|null"}}}}}},"security":[{"bearer":[]},{"session":[]}],"responses":{"200":{"description":"OK"},"4XX":{"description":"Error: {\"error\": \"...\"}"}}},"delete":{"summary":"Delete user with mailboxes and mail","description":"Auth: admin","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearer":[]},{"session":[]}],"responses":{"200":{"description":"OK"},"4XX":{"description":"Error: {\"error\": \"...\"}"}}}},"/admin/users/{id}/reset-password":{"post":{"summary":"Reset password (new one returned once)","description":"Auth: admin","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearer":[]},{"session":[]}],"responses":{"200":{"description":"OK"},"4XX":{"description":"Error: {\"error\": \"...\"}"}}}},"/admin/invites":{"get":{"summary":"All invites with who used them","description":"Auth: admin","parameters":[],"security":[{"bearer":[]},{"session":[]}],"responses":{"200":{"description":"OK"},"4XX":{"description":"Error: {\"error\": \"...\"}"}}},"post":{"summary":"Create invite","description":"Auth: admin","parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"note":{"description":"string?"},"max_uses":{"description":"1..1000"},"expires_in_days":{"description":"number?"}}}}}},"security":[{"bearer":[]},{"session":[]}],"responses":{"200":{"description":"OK"},"4XX":{"description":"Error: {\"error\": \"...\"}"}}}},"/admin/invites/{id}":{"delete":{"summary":"Revoke invite","description":"Auth: admin","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearer":[]},{"session":[]}],"responses":{"200":{"description":"OK"},"4XX":{"description":"Error: {\"error\": \"...\"}"}}}},"/admin/mailboxes":{"get":{"summary":"All mailboxes","description":"Auth: admin","parameters":[{"name":"q","in":"query","description":"q","schema":{"type":"string"}}],"security":[{"bearer":[]},{"session":[]}],"responses":{"200":{"description":"OK"},"4XX":{"description":"Error: {\"error\": \"...\"}"}}}},"/admin/mailboxes/{id}":{"delete":{"summary":"Delete mailbox","description":"Auth: admin","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearer":[]},{"session":[]}],"responses":{"200":{"description":"OK"},"4XX":{"description":"Error: {\"error\": \"...\"}"}}}},"/admin/settings":{"get":{"summary":"Global settings","description":"Auth: admin","parameters":[],"security":[{"bearer":[]},{"session":[]}],"responses":{"200":{"description":"OK"},"4XX":{"description":"Error: {\"error\": \"...\"}"}}},"put":{"summary":"Update settings","description":"Auth: admin","parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"anonymous_enabled":{"description":"boolean"},"domains_enabled":{"description":"string[]|null"},"default_max_mailboxes":{"description":"int"},"default_max_storage":{"description":"bytes"},"user_invites_enabled":{"description":"boolean"},"user_invite_limit":{"description":"int"}}}}}},"security":[{"bearer":[]},{"session":[]}],"responses":{"200":{"description":"OK"},"4XX":{"description":"Error: {\"error\": \"...\"}"}}}},"/admin/audit":{"get":{"summary":"Audit log of admin actions","description":"Auth: admin","parameters":[],"security":[{"bearer":[]},{"session":[]}],"responses":{"200":{"description":"OK"},"4XX":{"description":"Error: {\"error\": \"...\"}"}}}},"/admin/keys":{"get":{"summary":"List API keys","description":"Auth: admin (ADMIN_KEY or admin session)","parameters":[],"security":[{"bearer":[]},{"session":[]}],"responses":{"200":{"description":"OK"},"4XX":{"description":"Error: {\"error\": \"...\"}"}}},"post":{"summary":"Create API key (shown once)","description":"Auth: admin (ADMIN_KEY or admin session)","parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"description":"string"},"scopes":{"description":"mailboxes:read|mailboxes:write|pin|webhooks"}}}}}},"security":[{"bearer":[]},{"session":[]}],"responses":{"200":{"description":"OK"},"4XX":{"description":"Error: {\"error\": \"...\"}"}}}},"/admin/keys/{id}":{"delete":{"summary":"Revoke API key","description":"Auth: admin (ADMIN_KEY or admin session)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearer":[]},{"session":[]}],"responses":{"200":{"description":"OK"},"4XX":{"description":"Error: {\"error\": \"...\"}"}}}}}}