# Toma na Caixa

> Free, public, disposable email inboxes at @tomanacaixa.com with an open read-only JSON API. No sign-up, no API key. Any name@tomanacaixa.com receives mail instantly; messages are deleted after 48 hours. Built for humans and AI agents that need to receive verification codes or confirmation links.

Important:
- Inboxes are PUBLIC: anyone who knows a name can read it. Use random names (GET /v1/random) and never use them for real personal or financial accounts.
- Receive only. Sending email is not supported.
- Rate limit: 60 requests/minute per IP; max 3 concurrent wait/stream connections per IP.
- API base URL: https://api.tomanacaixa.com

## Agent quick start

1. `GET https://api.tomanacaixa.com/v1/random` → `{ "inbox": "...", "address": "...@tomanacaixa.com" }`
2. Use `address` wherever an email is required.
3. `GET https://api.tomanacaixa.com/v1/inboxes/{inbox}/wait?timeout=60` → blocks until mail arrives; read `messages[0].codes[0]` (extracted OTP) or `messages[0].links`.

## Docs

- [Agent skill (SKILL.md)](https://tomanacaixa.com/skill.md): step-by-step instructions for AI agents
- [OpenAPI 3.1 spec](https://tomanacaixa.com/openapi.json): machine-readable API description
- [API reference](https://tomanacaixa.com/en/docs): human-readable docs
- [Agent guide](https://tomanacaixa.com/en/agents): overview and examples

## Endpoints

- `GET /v1/random`: Get a random inbox name. Returns a fun, (probably) empty inbox name with its address and ready-made URLs. Ideal for agents.
- `GET /v1/inboxes/{name}/messages`: List inbox emails. Newest first, without full bodies (use the message endpoint for that). Includes extracted codes[].
- `GET /v1/inboxes/{name}/wait`: Wait for the next email (long-poll). 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.
- `GET /v1/inboxes/{name}/messages/{id}`: Read one email. Full message: text, sanitized HTML, links, codes and attachments.
- `GET /v1/inboxes/{name}/messages/{id}/raw`: Download the original email (.eml). The email exactly as received, with all headers (message/rfc822).
- `GET /v1/inboxes/{name}/messages/{id}/attachments/{index}`: Download an attachment. index comes from attachments[].index. Images open inline; everything else downloads.
- `GET /v1/inboxes/{name}/stream`: Real-time stream (SSE). 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.
- `GET /v1/stats`: Public stats. Global service counters.