---
name: tomanacaixa
description: Receive email with a free disposable inbox at @tomanacaixa.com — no sign-up or API key. Use when you need an email address to sign up for a service, receive a verification code (OTP), a magic link or a confirmation email, or to test an app that sends email. Provides a random address, a long-poll endpoint that waits for the next message, and extracted codes and links.
---

# Toma na Caixa: disposable inboxes for agents

Any `name@tomanacaixa.com` receives mail instantly. You read it through a public JSON API. Messages are deleted after 48 hours.

- **API base:** `https://api.tomanacaixa.com`
- **Web view:** `https://tomanacaixa.com/{name}`. Share it with the user so they can see the inbox too.
- **Auth:** none.
- **Rate limit:** 60 requests/min per IP. At most 3 concurrent `wait`/`stream` connections per IP.

## ⚠️ Rules before you use it

1. **Inboxes are public.** Anyone who knows the name can read them. Always use a random, hard-to-guess name from `/v1/random`, never something like `test` or `admin`.
2. **Never use it for the user's real accounts**: banking, primary email, anything with personal or financial data. It's for throwaway sign-ups, QA and testing.
3. **Receive only.** You cannot send email from these addresses.
4. Some sites block disposable domains. If a sign-up rejects the address, tell the user rather than retrying with other names.

## Workflow: get a verification code

### Step 1: get a unique address

```bash
curl -s https://api.tomanacaixa.com/v1/random
```

```json
{
  "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"
}
```

You can also invent your own name: 1–64 chars, `a-z 0-9 . _ -`, starting and ending with a letter or digit. Uppercase is lowercased, and `+tag` suffixes are delivered to the base name.

### Step 2: use the `address`

Fill it into the form or trigger the email. Remember the `inbox` value.

### Step 3: wait for the email (long-poll)

```bash
curl -s "https://api.tomanacaixa.com/v1/inboxes/goblin-dourado-4821/wait?timeout=60"
```

The request blocks until a message arrives, or until `timeout` seconds pass (1–90, default 60). Then:

- If `timed_out` is `false`, `messages` holds the full message(s), newest first.
- If `timed_out` is `true`, nothing arrived. Call `wait` again (a few times, if the service is slow) before giving up.

```json
{
  "inbox": "goblin-dourado-4821",
  "address": "goblin-dourado-4821@tomanacaixa.com",
  "timed_out": false,
  "count": 1,
  "messages": [
    {
      "id": "019a1b2c3d4e5f607182",
      "from": "noreply@example.com",
      "subject": "Your verification code",
      "codes": ["482913"],
      "links": ["https://example.com/confirm?token=abc"],
      "text": "Your code is 482913 ...",
      "html": "<p>...</p>",
      "received_at": "2026-10-24T15:04:05Z",
      "attachments": []
    }
  ]
}
```

### Step 4: extract what you need

- **OTP / code:** `messages[0].codes[0]`. Codes are ranked by likelihood, best first. If `codes` is empty or looks wrong, read `messages[0].text`.
- **Magic or confirmation link:** look in `messages[0].links` for the one matching the service domain and words like `confirm`, `verify` or `activate`. Open it with your browsing tool.

### Waiting for a *second* email

Pass the id of the last message you've seen as `since`. Only newer mail returns:

```bash
curl -s "https://api.tomanacaixa.com/v1/inboxes/goblin-dourado-4821/wait?timeout=60&since=019a1b2c3d4e5f607182"
```

## Other endpoints

| Method & path | Purpose |
|---|---|
| `GET /v1/inboxes/{name}/messages?since=&limit=` | List messages (no full body), newest first |
| `GET /v1/inboxes/{name}/messages/{id}` | One full message: `text`, `html`, `links`, `codes`, `attachments` |
| `GET /v1/inboxes/{name}/messages/{id}/raw` | Original `.eml` source |
| `GET /v1/inboxes/{name}/messages/{id}/attachments/{index}` | Download an attachment |
| `GET /v1/inboxes/{name}/stream` | Server-Sent Events, one `message` event per new email |
| `GET /v1/stats` | Public counters |

Errors are JSON: `{"error": "rate_limited", "message": "..."}`. On HTTP `429`, wait for the number of seconds in the `Retry-After` header.

## Snippets

### Python

```python
import requests
API = "https://api.tomanacaixa.com"
box = requests.get(f"{API}/v1/random").json()
# ... use box["address"] ...
r = requests.get(f"{API}/v1/inboxes/{box['inbox']}/wait", params={"timeout": 60}, timeout=70).json()
code = r["messages"][0]["codes"][0] if not r["timed_out"] and r["messages"][0]["codes"] else None
```

### JavaScript

```js
const API = "https://api.tomanacaixa.com";
const box = await fetch(`${API}/v1/random`).then(r => r.json());
// ... use box.address ...
const r = await fetch(`${API}/v1/inboxes/${box.inbox}/wait?timeout=60`).then(r => r.json());
const code = r.timed_out ? null : r.messages[0]?.codes[0];
```

### PowerShell

```powershell
$api = "https://api.tomanacaixa.com"
$box = Invoke-RestMethod "$api/v1/random"
# ... use $box.address ...
$r = Invoke-RestMethod "$api/v1/inboxes/$($box.inbox)/wait?timeout=60" -TimeoutSec 70
$r.messages[0].codes[0]
```

## Tips

- Tell the user which address you used and give them the `web_url`.
- Use one inbox per task or sign-up, so old mail doesn't confuse you.
- More references: full docs at https://tomanacaixa.com/en/docs and the OpenAPI spec at https://tomanacaixa.com/openapi.json.