# Inboxa — descrição completa

Última revisão: 2026-07-25. Versão da API: v0.

## O que é

Inboxa é infraestrutura de e-mail operada por API. Uma "caixa" (inbox) é um
endereço de e-mail real que recebe e envia mensagens como qualquer outro, mas
cujo dono é um programa: um agente de IA, um serviço de cobrança, um robô de
atendimento. O cliente fala HTTP com a Inboxa; SMTP, MX, DKIM, threading e
reputação de envio ficam do nosso lado.

Empresa brasileira, domínio inboxa.com.br. Domínio de fábrica das caixas:
inboxa.email. Domínios próprios do cliente são aceitos após verificação de DKIM
e SPF.

## Para que serve

Casos que a Inboxa cobre bem:

- Agente que atende clientes por e-mail e precisa responder na mesma conversa.
- Fluxo de cobrança que dispara mensagens e reage a respostas.
- Produto que dá a cada cliente final um endereço próprio, isolado.
- Sistema que precisa receber documentos por e-mail e processar anexos.

Casos que a Inboxa não cobre: marketing em massa, newsletter e disparo em lote
para listas compradas. O modo sandbox e a lista de supressão automática existem
justamente para impedir esse uso.

## Conceitos

- **Organização**: a conta. Tem plano, status de verificação e chaves.
- **Caixa (inbox)**: endereço de e-mail. Pertence a uma organização.
- **Thread**: conversa. Agrupa mensagens pelos cabeçalhos da RFC 5322.
- **Mensagem**: e-mail recebido (`inbound`) ou enviado (`outbound`).
- **Webhook**: notificação HTTP assinada, enviada ao endpoint do cliente.
- **Chave de API**: credencial `ibx_...`, com escopo de organização ou de caixa.

## Autenticação

Header `Authorization: Bearer ibx_...`. A chave é mostrada uma única vez, no
momento em que é criada; o servidor guarda apenas o hash. Chave com escopo
`inbox` acessa exatamente uma caixa e não pode criar caixas, chaves ou webhooks.

## Modo sandbox

Organização não verificada opera em sandbox: mensagens só circulam entre caixas
da própria Inboxa. Tentar enviar para um endereço externo devolve
`403 sandbox_restricted`. A verificação de CNPJ ou CPF libera o envio externo.

## Agrupamento em conversas (threading)

O critério principal são os cabeçalhos `In-Reply-To` e `References`, como define
a RFC 5322. Quando o cliente de e-mail do outro lado não envia esses cabeçalhos,
vale um critério secundário: assunto normalizado (sem `Re:`, `Enc:`, acentuação
e caixa) somado a pelo menos um interlocutor externo em comum, dentro de uma
janela de 30 dias. O endereço da própria caixa não conta como interlocutor —
sem isso, dois remetentes diferentes com o mesmo assunto cairiam na mesma
conversa.

## Entrega e retorno

Mensagem enviada nasce com `delivery_status: "queued"`. O envio real acontece de
forma assíncrona, com repetição em caso de falha. Os estados possíveis são
`queued`, `sent`, `delivered`, `bounced` e `complained`.

Bounce permanente e reclamação de spam adicionam o endereço a uma lista de
supressão da organização. Envios seguintes para esse endereço são recusados com
`403 recipient_blocked`.

## Webhooks

Eventos: `message.received`, `message.delivered`, `message.bounced`,
`message.complained`.

Cada entrega leva os headers `X-Inboxa-Event`, `X-Inboxa-Delivery` e
`X-Inboxa-Signature`, este último o HMAC-SHA256 do corpo cru usando o `secret`
devolvido na criação do webhook. Responda 2xx em até 10 segundos; falhas são
repetidas com backoff exponencial por até 24 horas.

Um webhook pode ser restrito a caixas específicas por `inbox_ids`. Lista vazia
significa todas as caixas da organização.

## Anexos

Anexos de envio vão em base64 no corpo JSON. Anexos recebidos são guardados em
object storage; `GET /v0/inboxes/{inbox_id}/attachments/{attachment_id}`
responde `302` com uma URL assinada que expira em 15 minutos. O binário não
trafega pela API.

## Busca

`GET /v0/inboxes/{inbox_id}/threads?q=...` faz busca full-text em assunto e
corpo, com dicionário português — acento e flexão não atrapalham.

## Paginação

Listagens aceitam `limit` (1 a 100, padrão 25) e `cursor`. A resposta traz
`next_cursor`, que é `null` na última página. O cursor é opaco e estável.

## Planos e limites

| Plano     | Preço (BRL/mês) | Caixas | E-mails enviados/mês | Armazenamento | Domínios próprios | Suporte por e-mail |
| --------- | --------------- | ------ | -------------------- | ------------- | ----------------- | ------------------ |
| Free      | 0               | 1      | 1.000                | 1 GB          | 0                 | não                |
| Developer | 19,90           | 5      | 5.000                | 5 GB          | 5                 | sim                |
| Startup   | 500             | 100    | 75.000               | 75 GB         | 75                | sim                |

O plano Free não pede cartão de crédito.

A cota de envio é por mês-calendário (UTC) e reabre no dia 1º. Ela conta apenas
mensagens enviadas: e-mail recebido não gasta cota de envio, ele ocupa
armazenamento. O armazenamento soma o MIME bruto e os anexos de todas as caixas
da organização.

Estourar a cota de envio devolve `403 plan_limit_exceeded`; estourar o
armazenamento devolve `403 storage_limit_exceeded`; passar do número de caixas
devolve `403 plan_limit_exceeded` na criação da caixa. Recebimento nunca é
recusado por cota — barrar e-mail que já entrou significaria perder mensagem do
cliente.

## Erros

Todo erro tem o formato `{"error": {"code": "...", "message": "..."}}`.

Códigos mais comuns: `unauthorized`, `validation_error`, `inbox_not_found`,
`message_not_found`, `thread_not_found`, `attachment_not_found`,
`webhook_not_found`, `address_taken`, `sandbox_restricted`, `recipient_blocked`,
`plan_limit_exceeded`, `storage_limit_exceeded`, `inbox_scoped_key`,
`domain_not_verified`, `invalid_cursor`, `rate_limited`.

## Limite de requisições

300 requisições por minuto por chave de API. Excedido, `429 rate_limited`.

## Como criar uma conta

1. Informe um e-mail em https://app.inboxa.com.br/criar-conta.
2. Um link de acesso é enviado para esse endereço, válido por 15 minutos e de
   uso único.
3. Abrir o link cria a organização em sandbox e a primeira chave de API,
   mostrada uma única vez.
4. A caixa não é criada automaticamente: quem escolhe o endereço é a pessoa, em
   `POST /v0/inboxes` ou pelo console.

Não há senha: o acesso ao console é sempre por link enviado ao e-mail.

## Primeira chamada

```
curl -X POST https://api.inboxa.com.br/v0/inboxes \
  -H "Authorization: Bearer ibx_..." \
  -H "Content-Type: application/json" \
  -d '{"username": "vendas", "display_name": "Agente de Vendas"}'
```

Resposta:

```
{
  "inbox_id": "ibx_in_9f8a7b",
  "address": "vendas@inboxa.email",
  "display_name": "Agente de Vendas",
  "pod_id": null,
  "sandbox": true,
  "created_at": "2026-07-25T12:00:00.000Z"
}
```

## Referências

- Contrato completo: https://inboxa.com.br/openapi.yaml
- Resumo curto: https://inboxa.com.br/llms.txt
- Console: https://app.inboxa.com.br
- Base da API: https://api.inboxa.com.br/v0