Skip to content
Reference

Toma na Caixa API

Public, read-only HTTP API in JSON. No authentication. CORS open to any origin.

Base URL
https://api.tomanacaixa.com
Authentication
None
Limits
60 req/min per IP · 3 concurrent waits/streams
Download OpenAPI 3.1

Get a random inbox name

GET/v1/random

Returns a fun, (probably) empty inbox name with its address and ready-made URLs. Ideal for agents.

Example

curl https://api.tomanacaixa.com/v1/random

Response

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

List inbox emails

GET/v1/inboxes/{name}/messages

Newest first, without full bodies (use the message endpoint for that). Includes extracted codes[].

Parameters

name*path · stringInbox name (the part before @). Lowercased; +tag is ignored.
sincequery · stringOnly messages newer than this id.
limitquery · integerMax messages (1–200, default 50).

Example

curl https://api.tomanacaixa.com/v1/inboxes/fada/messages

Response

{
  "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": []
    }
  ]
}

Wait for the next email (long-poll)

GET/v1/inboxes/{name}/wait

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*path · stringInbox name (the part before @). Lowercased; +tag is ignored.
sincequery · stringOnly messages newer than this id.
timeoutquery · integerSeconds to wait (1–90, default 60).

Example

curl "https://api.tomanacaixa.com/v1/inboxes/fada/wait?timeout=60"

Response

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

Read one email

GET/v1/inboxes/{name}/messages/{id}

Full message: text, sanitized HTML, links, codes and attachments.

Parameters

name*path · stringInbox name (the part before @). Lowercased; +tag is ignored.
id*path · stringMessage id (20 hex chars, time-sortable).

Example

curl https://api.tomanacaixa.com/v1/inboxes/fada/messages/019a1b2c3d4e5f607182

Response

{
  "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"
  ]
}

Download the original email (.eml)

GET/v1/inboxes/{name}/messages/{id}/raw

The email exactly as received, with all headers (message/rfc822).

Parameters

name*path · stringInbox name (the part before @). Lowercased; +tag is ignored.
id*path · stringMessage id (20 hex chars, time-sortable).

Example

curl -o email.eml https://api.tomanacaixa.com/v1/inboxes/fada/messages/019a1b2c3d4e5f607182/raw

Download an attachment

GET/v1/inboxes/{name}/messages/{id}/attachments/{index}

index comes from attachments[].index. Images open inline; everything else downloads.

Parameters

name*path · stringInbox name (the part before @). Lowercased; +tag is ignored.
id*path · stringMessage id (20 hex chars, time-sortable).
index*path · integerAttachment index.

Example

curl -OJ https://api.tomanacaixa.com/v1/inboxes/fada/messages/019a1b2c3d4e5f607182/attachments/0

Real-time stream (SSE)

GET/v1/inboxes/{name}/stream

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*path · stringInbox name (the part before @). Lowercased; +tag is ignored.
sincequery · stringOnly messages newer than this id.

Example

curl -N https://api.tomanacaixa.com/v1/inboxes/fada/stream

Public stats

GET/v1/stats

Global service counters.

Example

curl https://api.tomanacaixa.com/v1/stats

Response

{
  "total_received": 1234,
  "stored": 321,
  "active_inboxes": 87,
  "ttl_hours": 48
}

Message object

{
  "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"
  ]
}

Errors

Errors return JSON with error (code) and message (human-readable) fields.

HTTP/1.1 429 Too Many Requests
Retry-After: 12

{ "error": "rate_limited", "message": "..." }
  • 400 invalid_inbox / invalid_since
  • 404 not_found / reserved_inbox
  • 429 rate_limited / too_many_waits / too_many_streams