Pular para o conteúdo
Referência

API do Toma na Caixa

API HTTP pública, só leitura, em JSON. Sem autenticação. CORS liberado para qualquer origem.

URL base
https://api.tomanacaixa.com
Autenticação
Nenhuma
Limites
60 req/min por IP · 3 waits/streams simultâneos
Baixar OpenAPI 3.1

Sortear um nome de caixa

GET/v1/random

Devolve um nome divertido e (provavelmente) vazio, com o endereço e as URLs prontas. Ideal para agentes.

Exemplo

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

Resposta

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

Listar emails da caixa

GET/v1/inboxes/{name}/messages

Mensagens mais novas primeiro, sem o corpo completo (use o endpoint da mensagem para isso). Inclui codes[] já extraídos.

Parâmetros

name*path · stringNome da caixa (parte antes do @). Normalizado para minúsculas; +tag é ignorada.
sincequery · stringSó mensagens mais novas que este id.
limitquery · integerMáximo de mensagens (1–200, padrão 50).

Exemplo

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

Resposta

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

Esperar o próximo email (long-poll)

GET/v1/inboxes/{name}/wait

Segura a conexão até chegar um email mais novo que since (ou qualquer email, se since for omitido) e devolve as mensagens completas. Se o tempo acabar, responde timed_out: true. O jeito preferido para agentes.

Parâmetros

name*path · stringNome da caixa (parte antes do @). Normalizado para minúsculas; +tag é ignorada.
sincequery · stringSó mensagens mais novas que este id.
timeoutquery · integerSegundos para esperar (1–90, padrão 60).

Exemplo

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

Resposta

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

Ler um email

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

Mensagem completa: texto, HTML sanitizado, links, códigos e anexos.

Parâmetros

name*path · stringNome da caixa (parte antes do @). Normalizado para minúsculas; +tag é ignorada.
id*path · stringId da mensagem (20 caracteres hex, ordenável por tempo).

Exemplo

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

Resposta

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

Baixar o email original (.eml)

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

O email exatamente como chegou, com todos os cabeçalhos (message/rfc822).

Parâmetros

name*path · stringNome da caixa (parte antes do @). Normalizado para minúsculas; +tag é ignorada.
id*path · stringId da mensagem (20 caracteres hex, ordenável por tempo).

Exemplo

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

Baixar um anexo

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

index vem de attachments[].index. Imagens abrem inline; o resto é baixado.

Parâmetros

name*path · stringNome da caixa (parte antes do @). Normalizado para minúsculas; +tag é ignorada.
id*path · stringId da mensagem (20 caracteres hex, ordenável por tempo).
index*path · integerÍndice do anexo.

Exemplo

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

Stream em tempo real (SSE)

GET/v1/inboxes/{name}/stream

Server-Sent Events: um evento message (JSON da mensagem) para cada email novo. Envia comentários de keepalive a cada 20s e fecha após 30 min. Suporta Last-Event-ID.

Parâmetros

name*path · stringNome da caixa (parte antes do @). Normalizado para minúsculas; +tag é ignorada.
sincequery · stringSó mensagens mais novas que este id.

Exemplo

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

Estatísticas públicas

GET/v1/stats

Contadores globais do serviço.

Exemplo

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

Resposta

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

Objeto Message

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

Erros

Erros respondem JSON com os campos error (código) e message (texto legível).

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