{"openapi":"3.1.0","info":{"title":"Toma na Caixa API","version":"1.0.0","description":"Free, public, read-only API for disposable inboxes at @tomanacaixa.com. No authentication. Emails expire after 48h. Rate limit: 60 requests/min per IP. Inboxes are public: anyone who knows a name can read it.","contact":{"url":"https://tomanacaixa.com/agentes"}},"servers":[{"url":"https://api.tomanacaixa.com"}],"paths":{"/v1/random":{"get":{"operationId":"random","summary":"Get a random inbox name","description":"Returns a fun, (probably) empty inbox name with its address and ready-made URLs. Ideal for agents.","parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"inbox":"goblin-dourado-4821","address":"goblin-dourado-4821@tomanacaixa.com","web_url":"https://tomanacaixa.com/goblin-dourado-4821","api_url":"https://api.tomanacaixa.com/v1/inboxes/goblin-dourado-4821/messages","wait_url":"https://api.tomanacaixa.com/v1/inboxes/goblin-dourado-4821/wait"}}}},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/v1/inboxes/{name}/messages":{"get":{"operationId":"list","summary":"List inbox emails","description":"Newest first, without full bodies (use the message endpoint for that). Includes extracted codes[].","parameters":[{"name":"name","in":"path","required":true,"description":"Inbox name (the part before @). Lowercased; +tag is ignored.","schema":{"type":"string"},"example":"fada"},{"name":"since","in":"query","required":false,"description":"Only messages newer than this id.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Max messages (1–200, default 50).","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageList"},"example":{"inbox":"fada","address":"fada@tomanacaixa.com","web_url":"https://tomanacaixa.com/fada","ttl_hours":48,"count":1,"messages":[{"id":"019a1b2c3d4e5f607182","inbox":"fada","from":"noreply@loja.example","from_name":"Loja Exemplo","to":"fada@tomanacaixa.com","subject":"Seu código de verificação","preview":"Seu código é 482913. Confirme em https://loja.example/confirm?t=abc","codes":["482913"],"size":2048,"received_at":"2026-10-24T15:04:05Z","expires_at":"2026-10-26T15:04:05Z","attachments":[]}]}}}},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/v1/inboxes/{name}/wait":{"get":{"operationId":"wait","summary":"Wait for the next email (long-poll)","description":"Holds the connection until an email newer than since arrives (or any email, if since is omitted) and returns the full messages. On timeout it responds timed_out: true. The preferred way for agents.","parameters":[{"name":"name","in":"path","required":true,"description":"Inbox name (the part before @). Lowercased; +tag is ignored.","schema":{"type":"string"},"example":"fada"},{"name":"since","in":"query","required":false,"description":"Only messages newer than this id.","schema":{"type":"string"}},{"name":"timeout","in":"query","required":false,"description":"Seconds to wait (1–90, default 60).","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageList"},"example":{"inbox":"fada","address":"fada@tomanacaixa.com","web_url":"https://tomanacaixa.com/fada","ttl_hours":48,"count":1,"messages":[{"id":"019a1b2c3d4e5f607182","inbox":"fada","from":"noreply@loja.example","from_name":"Loja Exemplo","to":"fada@tomanacaixa.com","subject":"Seu código de verificação","preview":"Seu código é 482913. Confirme em https://loja.example/confirm?t=abc","codes":["482913"],"size":2048,"received_at":"2026-10-24T15:04:05Z","expires_at":"2026-10-26T15:04:05Z","attachments":[],"text":"Seu código é 482913. Confirme em https://loja.example/confirm?t=abc","html":"<p>Seu código é <b>482913</b></p>","links":["https://loja.example/confirm?t=abc"]}],"timed_out":false}}}},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/v1/inboxes/{name}/messages/{id}":{"get":{"operationId":"get","summary":"Read one email","description":"Full message: text, sanitized HTML, links, codes and attachments.","parameters":[{"name":"name","in":"path","required":true,"description":"Inbox name (the part before @). Lowercased; +tag is ignored.","schema":{"type":"string"},"example":"fada"},{"name":"id","in":"path","required":true,"description":"Message id (20 hex chars, time-sortable).","schema":{"type":"string"},"example":"019a1b2c3d4e5f607182"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Message"},"example":{"id":"019a1b2c3d4e5f607182","inbox":"fada","from":"noreply@loja.example","from_name":"Loja Exemplo","to":"fada@tomanacaixa.com","subject":"Seu código de verificação","preview":"Seu código é 482913. Confirme em https://loja.example/confirm?t=abc","codes":["482913"],"size":2048,"received_at":"2026-10-24T15:04:05Z","expires_at":"2026-10-26T15:04:05Z","attachments":[],"text":"Seu código é 482913. Confirme em https://loja.example/confirm?t=abc","html":"<p>Seu código é <b>482913</b></p>","links":["https://loja.example/confirm?t=abc"]}}}},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/v1/inboxes/{name}/messages/{id}/raw":{"get":{"operationId":"raw","summary":"Download the original email (.eml)","description":"The email exactly as received, with all headers (message/rfc822).","parameters":[{"name":"name","in":"path","required":true,"description":"Inbox name (the part before @). Lowercased; +tag is ignored.","schema":{"type":"string"},"example":"fada"},{"name":"id","in":"path","required":true,"description":"Message id (20 hex chars, time-sortable).","schema":{"type":"string"},"example":"019a1b2c3d4e5f607182"}],"responses":{"200":{"description":"OK","content":{"message/rfc822":{}}},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/v1/inboxes/{name}/messages/{id}/attachments/{index}":{"get":{"operationId":"attachment","summary":"Download an attachment","description":"index comes from attachments[].index. Images open inline; everything else downloads.","parameters":[{"name":"name","in":"path","required":true,"description":"Inbox name (the part before @). Lowercased; +tag is ignored.","schema":{"type":"string"},"example":"fada"},{"name":"id","in":"path","required":true,"description":"Message id (20 hex chars, time-sortable).","schema":{"type":"string"},"example":"019a1b2c3d4e5f607182"},{"name":"index","in":"path","required":true,"description":"Attachment index.","schema":{"type":"integer"},"example":"0"}],"responses":{"200":{"description":"OK","content":{"application/octet-stream":{}}},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/v1/inboxes/{name}/stream":{"get":{"operationId":"stream","summary":"Real-time stream (SSE)","description":"Server-Sent Events: one message event (message JSON) per new email. Sends keepalive comments every 20s and closes after 30 min. Supports Last-Event-ID.","parameters":[{"name":"name","in":"path","required":true,"description":"Inbox name (the part before @). Lowercased; +tag is ignored.","schema":{"type":"string"},"example":"fada"},{"name":"since","in":"query","required":false,"description":"Only messages newer than this id.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"text/event-stream":{}}},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/v1/stats":{"get":{"operationId":"stats","summary":"Public stats","description":"Global service counters.","parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"total_received":1234,"stored":321,"active_inboxes":87,"ttl_hours":48}}}},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}}},"components":{"schemas":{"Message":{"type":"object","properties":{"id":{"type":"string","description":"Time-sortable id (20 hex chars)"},"inbox":{"type":"string"},"from":{"type":"string","description":"Sender address"},"from_name":{"type":"string"},"to":{"type":"string"},"subject":{"type":"string"},"preview":{"type":"string","description":"First ~160 chars of text"},"text":{"type":"string","description":"Plain-text body (full message only)"},"html":{"type":"string","description":"Sanitized HTML body (full message only)"},"codes":{"type":"array","items":{"type":"string"},"description":"Likely verification codes, best first"},"links":{"type":"array","items":{"type":"string"},"description":"http(s) links found (full message only)"},"size":{"type":"integer"},"received_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time"},"attachments":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"filename":{"type":"string"},"content_type":{"type":"string"},"content_id":{"type":"string"},"inline":{"type":"boolean"},"size":{"type":"integer"}}}}}},"MessageList":{"type":"object","properties":{"inbox":{"type":"string"},"address":{"type":"string"},"web_url":{"type":"string"},"ttl_hours":{"type":"integer"},"count":{"type":"integer"},"timed_out":{"type":"boolean","description":"Only on /wait"},"messages":{"type":"array","items":{"$ref":"#/components/schemas/Message"}}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}},"responses":{"Error":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}