---
title: Caixas de entrada
description: Endereços de e-mail que guardam as mensagens em conversas e respondem pelo mesmo endereço, para um agente de IA ou para pessoas.
ai:
  exclude: true
---

Uma caixa de entrada é um endereço de e-mail que recebe mensagens em conversas e envia pelo mesmo endereço. Dê uma para um agente de IA, que lê pela API, por webhooks ou pelo [servidor MCP](/docs/pt-br/mcp), ou para pessoas, que leem pelo painel. Uma caixa é um endereço de um dos seus [domínios de recebimento](/docs/pt-br/receiving), ou um endereço no domínio compartilhado do BillionSend, que não precisa de DNS.

Os [SDKs](/docs/pt-br/sdks) cobrem todos os endpoints de caixas de entrada como `inboxes.*`, incluindo as regras de segurança, a quarentena, as aprovações e o fluxo de eventos em tempo real.

> **Info**
>
> As caixas de entrada estão em beta, em **Caixas de entrada** no painel.

## Agente ou pessoas

Toda caixa tem um `kind`, escolhido na criação e que nunca muda. O tipo define os padrões das configurações de segurança.

| Configuração | Agente | Pessoas |
| --- | --- | --- |
| `accept_from` | `verified` | `anyone` |
| `screening` | ligada | desligada |
| `extract_codes` | ligada | ligada |
| `send_policy` | `reply_only` | `open` (`reply_only` no domínio compartilhado) |
| `require_approval` | desligada | desligada |
| `private_codes` | ligada | desligada |
| `send_cap` | 200 (50 no domínio compartilhado) | sem limite (50 no domínio compartilhado) |

- **`agent`** é o padrão quando `kind` é omitido. E-mails de remetentes cujo domínio não os garante esperam na quarentena, e-mails dos demais remetentes externos passam pela análise de injeção de prompt, e o agente responde dentro das conversas existentes: uma conversa nova que ele começa vira um rascunho que espera uma pessoa. Veja [Segurança do agente](/docs/pt-br/agent-safety).
- **`human`** é para pessoas que leem pelo painel: o e-mail de todos é entregue (uma autenticação reprovada cai na pasta `spam`) e nada passa pela análise.

E-mail com vírus vai para a quarentena em toda caixa.

## Criar uma caixa de entrada

No painel, abra **Caixas de entrada** e escolha **Criar caixa de entrada**. Ou chame a API:

```sh
curl -X POST "https://api.billionsend.com/inboxes" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -d '{
    "email_address": "orders@inbound.example.com",
    "name": "Agente de pedidos",
    "kind": "agent"
  }'
```

Com o SDK para Node.js:

```ts
import { BillionSend } from "@billionsend/node";

const bs = new BillionSend(); // reads BILLIONSEND_API_KEY

const { data, error } = await bs.inboxes.create({
  email_address: "orders@inbound.example.com",
  name: "Orders agent",
  kind: "agent",
});
```

A resposta (`201`) é a caixa inteira: `id`, `name`, `email_address`, `domain_id`, `kind`, `shared`, `expires_at`, `unread` (conversas com mensagem não lida), `drafts`, `quarantined`, `pending_approval` e mais.

| Campo | Regras |
| --- | --- |
| `email_address` | Um endereço de um domínio verificado da sua equipe que recebe e-mails. Em minúsculas; a parte antes do `@` aceita até 64 letras, dígitos e `. _ % + -`. Não pode mudar depois. Omita para um endereço no domínio compartilhado. |
| `username` | Com `email_address` omitido, a parte antes do `@` no domínio compartilhado; omitido, o endereço é aleatório. Com o `domain_id` de um dos seus domínios, é a parte antes do `@` nele. |
| `domain_id` | Uma linha de `GET /domains`: o subdomínio compartilhado da sua equipe (`shared: true`) ou um dos seus domínios verificados. |
| `name` | 1 a 320 caracteres; o endereço, quando omitido. |
| `from_name` | Nome de exibição dos e-mails que a caixa envia, até 78 caracteres: um nome simples, sem `@`, `:`, `<`, `>`, quebras de linha, links nem telefones. |
| `kind` | `agent` (padrão) ou `human`. |
| `expires_in` | Quando a caixa expira, como `1h`, `24h` ou `7d`; omitido, nunca. |
| `safety` | Qualquer uma das configurações de segurança. |
| `forwarding` | `true` acrescenta um `receiving_address` no domínio compartilhado, para encaminhar para a caixa uma conta de e-mail que você mantém em outro lugar. |

| Resposta | Quando |
| --- | --- |
| `409 validation_error` | Outra caixa já usa o endereço. Nenhum outro nome é escolhido por você. |
| `403 validation_error` | O limite de caixas do seu plano foi atingido. |
| `429 rate_limit_exceeded` | Caixas demais criadas na última hora, ou a análise de nomes do domínio compartilhado atingiu o limite de hoje. `retry-after` diz quando tentar de novo. |
| `422 validation_error` | O domínio não está verificado ou não recebe e-mails, um `username` quebra uma regra ou é reservado, ou uma configuração quebra uma regra. |
| `503 name_review_unavailable` | Não foi possível analisar agora um nome do domínio compartilhado. Tente de novo em instantes. |

As outras chamadas:

- `GET /inboxes` lista as caixas, da mais nova à mais antiga (`?kind=agent` ou `?kind=human` restringe).
- `GET /inboxes/{id}` lê uma. Todo `{id}` de um caminho `/inboxes/{id}/…` aceita o id da caixa ou o endereço de e-mail dela.
- `PATCH /inboxes/{id}` altera `name`, `from_name` ou `expires_in`.
- `DELETE /inboxes/{id}` exclui a caixa com suas conversas, rascunhos e etiquetas, e revoga as chaves de API dela. Uma mensagem que também chegou a outra caixa ou a um endereço do pega-tudo continua lá.

## Endereços

### No seu domínio

Uma caixa no seu domínio exige que o domínio [receba e-mails](/docs/pt-br/receiving): verificado, com o recebimento ligado e o registro MX publicado. Cada mensagem segue o endereço para o qual o servidor do remetente a entregou:

1. para a caixa com exatamente esse endereço;
2. senão, para `name+tag@`, para a caixa de `name@`;
3. senão, quando o pega-tudo do domínio está ligado, para **Todos os recebidos** sem caixa; com o pega-tudo desligado, o endereço é recusado (`550 5.1.1`).

O e-mail enviado do endereço de uma caixa segue as regras da caixa em todas as vias: `POST /emails`, o endpoint em lote, o relay SMTP e o MCP. Dê à caixa um endereço que o seu app ainda não use para enviar.

### Domínio compartilhado

Uma caixa no domínio compartilhado não precisa de DNS. Cada equipe tem um subdomínio próprio no domínio compartilhado do BillionSend, com o nome da equipe. Omita `email_address`, ou envie o id da linha compartilhada como `domain_id`, e `username` dá o nome do endereço:

```sh
curl -X POST "https://api.billionsend.com/inboxes" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -d '{ "username": "orders", "name": "Agente de pedidos" }'
```

Sem `username`, o endereço é aleatório. Um nome de usuário é recusado (`422`) quando é reservado (postmaster, abuse, admin, security, support, noreply, no-reply, billing, hostmaster, webmaster, mailer-daemon, root), começa com `fwd-` ou parece uma marca conhecida. Um já em uso responde `409`.

**Análise de nomes.** Um nome de usuário escolhido, um `from_name` e o subdomínio da equipe são analisados antes de serem publicados, para barrar nomes que se passam por uma marca, um banco, um governo ou um cargo oficial. Um nome recusado responde `422`. Enquanto a análise não consegue responder, você recebe `503 name_review_unavailable`; o subdomínio de uma equipe nova é tentado de novo até passar, e após 24 horas a equipe fica com `team-` e seis caracteres aleatórios. Passados 20 nomes recusados ou 200 análises num dia UTC, a resposta é `429` até a meia-noite UTC.

Os endereços compartilhados seguem regras próprias, já que o domínio é de todas as equipes:

- Duram até serem excluídos, a menos que `expires_in` diga outra coisa, e contam para o limite de caixas do seu plano. Uma que ninguém usa há 90 dias é excluída.
- No plano **Free**, e em qualquer endereço cujo nome pareça uma marca conhecida, eles só respondem dentro das próprias conversas, a remetentes cujo domínio os garantiu e aos endereços de login dos membros da sua equipe. Num plano pago, pessoas começam conversas por eles, e um agente também começa quando o `send_policy` é `open` e a sua equipe já passou dos primeiros envios; caso contrário, as conversas novas dele esperam uma pessoa como rascunhos. Cada mensagem a um desconhecido é verificada contra phishing antes de sair. Uma recusa responde `403 inbox_send_policy`.
- Cada e-mail vai para no máximo 10 destinatários. Uma caixa envia a no máximo 50 destinatários por dia (`send_cap` de 1 a 50), e todos os endereços compartilhados da sua equipe juntos chegam a 1.000 destinatários por dia UTC; além disso, `429 inbox_send_cap_reached`.
- `from` precisa ser exatamente o endereço da caixa, e o e-mail não pode ter `scheduled_at`, `reply_to`, anexos nem cabeçalhos personalizados (`422`). `POST /emails/batch`, broadcasts e o relay SMTP sempre recusam um endereço compartilhado.
- `forward_to` aceita só endereços de login de membros.

Os e-mails para `postmaster@` e `abuse@` no domínio compartilhado vão para o BillionSend, nunca para uma caixa.

### Encaminhar uma conta de e-mail para uma caixa

`forwarding: true` é para um endereço cujos e-mails ficam em outro lugar, como uma conta do Google Workspace. A caixa ganha um `receiving_address`, um endereço aleatório no subdomínio compartilhado da sua equipe: encaminhe a conta para lá, e a caixa recebe os e-mails e responde pelo próprio endereço. O domínio só precisa estar verificado para envio.

## Validade

`expires_in` é um número seguido de `h` ou `d`, de `1h` a `365d`; omitido, a caixa nunca expira. Um `PATCH` com um novo `expires_in` conta a partir desse momento, e `null` remove a validade. `expires_at` mostra quando ela termina.

Em `expires_at` a caixa para: os e-mails para ela são recusados (`550 5.1.1`), as leituras respondem `404` e as chaves de API dela deixam de funcionar. Dentro de uma hora ela é excluída, com um webhook `inbox.expired` seguido de `inbox.deleted`. Alterar a validade exige a função de desenvolvedor, administrador ou proprietário.

## Conversas

Toda mensagem de uma caixa pertence a uma conversa, e uma conversa guarda os dois sentidos: o que a caixa recebeu e o que enviou.

- **Como as respostas encontram a conversa.** O e-mail que a caixa envia leva um token de conversa no cabeçalho `References`. Uma resposta cai na mesma conversa quando leva esse token, quando o `In-Reply-To` dela cita uma mensagem que a caixa enviou, ou quando ela se refere a uma mensagem anterior da conversa. Assuntos nunca juntam conversas.
- **Pastas.** Uma conversa fica em uma pasta: `inbox`, `archive`, `spam`, `sent` ou `trash`. Um e-mail novo move uma conversa arquivada ou enviada de volta para `inbox`. `DELETE` move a conversa para `trash`, que é esvaziada após 30 dias.
- **Lido/não lido.** Um `PATCH` com `read` marca a conversa inteira. Um e-mail retido nunca deixa uma conversa não lida. Numa caixa de pessoas, abrir uma conversa a marca como lida; numa caixa de agente, o estado de leitura pertence ao seu agente.
- **Etiquetas.** Até 100 por caixa, nomes de 1 a 64 caracteres, cores como `#RRGGBB`.

| Chamada | Faz |
| --- | --- |
| `GET /inboxes/{id}/threads` | Conversas, da atividade mais recente. Filtros: `folders`, `labels`, `read`, `include_quarantined`. |
| `GET /inboxes/{id}/threads/search` | Os mesmos filtros mais `query` (`"frase exata"` e `-excluído` funcionam), `from`, `to`, `cc`, `bcc`, `has_attachment`, `start_date`, `end_date`. |
| `GET /inboxes/{id}/threads/{thread_id}` | Uma conversa. |
| `PATCH /inboxes/{id}/threads/{thread_id}` | Define `read` ou `folder`. |
| `POST` / `PUT` / `DELETE …/threads/{thread_id}/labels` | Adiciona, substitui ou remove etiquetas. |
| `DELETE /inboxes/{id}/threads/{thread_id}` | Move a conversa para a lixeira. |
| `GET /inboxes/{id}/threads/{thread_id}/emails` | Seus e-mails, do mais antigo ao mais novo. |

A busca encontra palavras inteiras, sem diferenciar maiúsculas e minúsculas, no assunto, no remetente (endereço e nome de exibição), nos destinatários, no texto de um e-mail recebido (incluindo as mensagens anteriores que ele cita), nos nomes dos anexos dele e no texto dos anexos em PDF, Word e Excel (depois que esse texto é lido). Textos em chinês, japonês e coreano são divididos em palavras. Cada palavra de `query` precisa aparecer em algum lugar do mesmo e-mail; `from`, `to`, `cc` e `bcc` recebem palavras de um endereço ou de um nome. Os e-mails enviados são buscados pelo assunto, pelo remetente e pelos destinatários.

`matched_email_id` é o e-mail da conversa que melhor corresponde à busca, e `highlights` marca as palavras no assunto, no remetente e nos destinatários dele (fica `{}` quando só o texto ou o nome de um anexo correspondeu). Um e-mail novo pode ser buscado um ou dois segundos depois de chegar. Se a busca estiver indisponível por um momento, a chamada responde `503` com `search_unavailable` e um cabeçalho `Retry-After`; todas as outras chamadas funcionam normalmente.

Um e-mail de conversa tem `direction`, `from`, `to`, `cc`, `bcc`, `reply_to`, `subject`, `message_id`, `html`, `text`, `attachments`, `read` e `received_at`. O e-mail recebido acrescenta `extracted_text` (a resposta, limpa de texto oculto), `screening`, `spam_verdict` e `virus_verdict`.

## Enviar de uma caixa

`POST /inboxes/{id}/emails` (`inboxes.send()` nos SDKs) inicia uma nova conversa a partir do endereço da caixa numa única chamada.

```sh
curl -X POST "https://api.billionsend.com/inboxes/{id}/emails" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-confirmation" \
  -d '{
    "to": "ada@example.org",
    "subject": "Seu pedido 1042",
    "text": "Ele sai hoje. A nota fiscal está anexada.",
    "attachments": [{ "filename": "invoice.pdf", "content": "JVBERi0xLjQK..." }]
  }'
```

Ela aceita `to`, `subject`, `html` e/ou `text`, e opcionalmente `cc`, `bcc`, `attachments` e `requires_approval`. As regras da caixa decidem como numa resposta, e as respostas são as de uma resposta: `200` com `{ "id", "thread_id" }`, ou `202` com o rascunho quando as regras seguram o envio (uma caixa que não pode iniciar conversas, um destinatário novo além da rampa, `requires_approval: true`). Uma chave restrita a uma caixa pode chamá-la para a própria caixa.

Os **anexos** são os que o `POST /emails` aceita: `filename` e `content` em base64, e opcionalmente `content_type` e `content_id` para uma imagem embutida. Um `path` remoto responde `422`. Respostas, encaminhamentos, envios novos e rascunhos aceitam anexos, até 10 MiB decodificados no total (um encaminhamento conta também os arquivos do original); programas e tipos de arquivo disfarçados respondem `422`, e uma caixa no domínio compartilhado não aceita nenhum.

## Responder e encaminhar

```sh
curl -X POST "https://api.billionsend.com/inboxes/{id}/threads/{thread_id}/emails/{email_id}/reply" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-reply" \
  -d '{ "text": "Obrigado, seu pedido sai hoje." }'
```

Uma resposta vai para o `Reply-To` da mensagem, ou então para o remetente. `reply_all` acrescenta os outros endereços de `to` e `cc` como `cc`; `bcc` nunca é copiado. Um envio aceita no máximo 50 destinatários. `…/forward` exige `to`, aceita uma nota e cita o original com seus anexos, mais os `attachments` que você acrescentar (até 10 MiB no total). Ambos aceitam `attachments` e `requires_approval: true` para uma pessoa aprovar o envio. Uma resposta de uma caixa de agente leva `Auto-Submitted: auto-replied`.

| Resposta | Significa |
| --- | --- |
| `200` | Enviado: `{ "id", "thread_id" }`. |
| `202` | Retido para uma pessoa: o rascunho, com `status: "pending_approval"` e seus `approval_reasons`. |
| `403 inbox_send_policy` | As regras da caixa recusam o envio de vez. |
| `403 email_quarantined` | O e-mail está retido na quarentena ou tem vírus. |
| `403 restricted_api_key` | Uma chave restrita a uma caixa tentando alcançar outra. |
| `429 inbox_send_cap_reached` | O limite diário da caixa foi usado; `retry-after` conta até a meia-noite UTC. |

Para responder a qualquer e-mail recebido, numa caixa ou não, use [`POST /emails/receiving/{id}/reply`](/docs/pt-br/receiving).

## Rascunhos e aprovação

Um rascunho é avulso, para uma conversa nova, ou uma resposta com `thread_id` e `reply_to_email_id`. O seu `status`:

| `status` | Significa |
| --- | --- |
| `draft` | Sendo escrito; nada o envia até `…/send`, ou até o seu `send_at`. |
| `pending_approval` | Um envio foi retido e espera uma pessoa. `approval_reasons` diz por quê. Expira em 7 dias. |
| `sent` | Enviado; `email_id` indica o e-mail. |
| `rejected` | Uma pessoa o descartou. |
| `expired` | Ninguém aprovou em 7 dias. |

| Chamada | Faz |
| --- | --- |
| `POST /inboxes/{id}/drafts` | Cria um rascunho: `to`, `cc`, `bcc`, `subject`, `text`, `html`, `attachments`, mais `thread_id` e `reply_to_email_id` para uma resposta. Um rascunho de resposta não copia os destinatários, então defina `to` antes de enviar. |
| `GET /inboxes/{id}/drafts` | Rascunhos não enviados, do atualizado mais recentemente. |
| `GET` / `PATCH` / `DELETE /inboxes/{id}/drafts/{draft_id}` | Lê, altera (definir `text` ou `html` substitui o corpo inteiro, e `attachments` substitui a lista inteira) ou exclui um rascunho; `409` depois de enviado. |
| `POST /inboxes/{id}/drafts/{draft_id}/send` | Envia. `200` com o `id` e o `thread_id` do e-mail enviado, `202` quando retido, `422` sem destinatário. |
| `POST /inboxes/{id}/drafts/{draft_id}/reject` | Descarta um rascunho (só quem aprova). |

Um rascunho guarda os `attachments` criptografados, à parte do corpo, e os devolve por posição como `id`, `filename`, `content_type` e `size`, nunca o conteúdo. Eles saem com o e-mail quando o rascunho é enviado, e um envio retido guarda com o rascunho os arquivos que levava. Depois que um rascunho é enviado, descartado, expira ou é excluído, os arquivos dele somem, e a limpeza de conteúdo de 30 dias remove os que sobrarem.

**Envios agendados.** `send_at` no `POST` ou no `PATCH` (uma extensão do BillionSend) envia o rascunho depois, em nome de quem o definiu (editar o conteúdo de um rascunho agendado faz o envio sair em nome de quem editou): um horário ISO 8601 com fuso, ou um relativo como `"in 2 hours"`, no máximo 30 dias à frente; um horário que já passou envia em até um minuto, e `null` cancela. O rascunho precisa ter um destinatário até lá, e só um `draft` pode ser agendado: um que espera aprovação responde `409`. Quando chega o `send_at`, o envio passa por todas as regras e limites, como um envio feito naquele momento. Enviado, o rascunho fica `sent`; retido pelas regras da caixa, `pending_approval`; recusado (a chave que o agendou foi revogada, a caixa não existe mais, um limite foi atingido), ele continua `draft`, com `send_at` de volta a `null`, o nome da recusa em `send_error` e um webhook `inbox.draft.send_failed` que traz `error: { name, message }`. Agendar de novo limpa o `send_error`. Com `send_at`, criar um segundo rascunho de resposta para o mesmo e-mail responde `409` em vez do rascunho existente.

**Quem aprova.** Uma pessoa no painel, ou uma chave de API de acesso total da equipe que não seja restrita a uma caixa, aprova enviando: o envio pula as regras que seguram o e-mail de agentes. Um agente não aprova: uma chave restrita a uma caixa ou um cliente MCP que envia um rascunho pendente recebe `403 approval_required`. No painel, qualquer membro aprova, edita ou descarta rascunhos na aba **Precisa de revisão** da caixa, e os proprietários recebem um e-mail por dia enquanto houver algo à espera.

Motivos pelos quais um envio é retido:

| Motivo | Retido porque |
| --- | --- |
| `approval_required` | A requisição pediu uma pessoa (`requires_approval: true`). |
| `require_approval` | A caixa exige aprovação em todo envio. |
| `send_policy` | Um destinatário não é permitido pela regra de envio da caixa. |
| `ramp` | Destinatários novos demais hoje para uma caixa recente. |
| `private_code` | Contém um código ou link de acesso que a caixa recebeu. |
| `loop_guard:<motivo>` | Responde a uma mensagem automática (resposta de ausência, lista de e-mails, retorno de erro). |
| `loop_burst` | Respostas automáticas demais a um mesmo endereço em uma hora. |
| `reply_to_redirect` | O Reply-To da mensagem aponta para outra organização. |

## Configurações de segurança

`GET /inboxes/{id}/safety` lê as regras de uma caixa, e `PATCH` altera qualquer uma:

```sh
curl -X PATCH "https://api.billionsend.com/inboxes/{id}/safety" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -d '{
    "accept_from": "allowlist",
    "allowlist": ["*@billing.example.net", "maria@example.org"]
  }'
```

| Configuração | Faz |
| --- | --- |
| `accept_from` | Quem alcança a caixa: `anyone`; `verified`, remetentes cujo domínio garante o endereço From (mais proprietários, a lista de permitidos e conversas conhecidas); ou `allowlist`, só proprietários, a lista de permitidos e conversas conhecidas. O resto vai para a quarentena. |
| `allowlist` | Até 500 entradas: `name@domain`, ou `*@domain` para um domínio e seus subdomínios. |
| `owner_addresses` | Até 50 endereços a mais tratados como responsáveis pela caixa, além dos endereços de login dos membros da equipe. Ignorado no domínio compartilhado. |
| `screening` | Dá nota de injeção de prompt e phishing aos e-mails de remetentes externos (caixas de agente). |
| `extract_codes` | Extrai códigos de verificação e links de acesso dos e-mails. |
| `send_policy` | `reply_only`; `allowlist`, que acrescenta conversas novas com proprietários e a lista de permitidos (não no domínio compartilhado); ou `open`, qualquer pessoa, depois que a equipe passa dos primeiros envios. |
| `require_approval` | Todo envio da caixa espera uma pessoa. |
| `private_codes` | Um código ou link de acesso que a caixa recebeu não pode ser enviado a ninguém além dos proprietários e da lista de permitidos. |
| `send_cap` | Destinatários a quem a caixa pode enviar por dia UTC sem uma pessoa: de 1 a 100.000, ou `null` para sem limite (de 1 a 50 no domínio compartilhado). |
| `forward_to` | Até 5 endereços que recebem cópia de toda mensagem entregue, exceto spam: endereços de login de membros ou endereços de responsáveis. Uma cópia que não pode sair de imediato é tentada de novo até ser enviada, recusada em definitivo ou passarem dois dias; nunca é enviada duas vezes. |

Uma configuração que quebra uma regra responde `422` com o motivo. Uma chave restrita a uma caixa não altera essas configurações (`403 restricted_api_key`), e uma chave de agente também não. Um cliente MCP pode lê-las, mas não alterá-las. Só um proprietário, administrador ou desenvolvedor as altera, no painel ou com uma chave de API de acesso total. A [Segurança do agente](/docs/pt-br/agent-safety) explica o que cada uma faz.

## Quarentena

O e-mail que as regras de uma caixa não deixam entrar vai para a quarentena: guardado, listado e liberável, nunca descartado e nunca devolvido ao remetente. Não dispara `email.received` nem `inbox.email.received` até ser liberado, e os agentes nunca o veem.

`GET /inboxes/{id}/quarantine` lista as mensagens retidas com `id`, `from`, `subject`, `quarantine_reason`, `sender_trust`, `injection_score`, `phishing_score` e `virus_signature`, sem o conteúdo. `POST /inboxes/{id}/quarantine/{email_id}/release` entrega uma, e `{ "trust_sender": true }` também coloca o remetente na lista de permitidos. Ambos exigem uma chave de acesso total que não seja restrita a uma caixa. Pessoas liberam pela aba **Precisa de revisão** da caixa, e clientes MCP com `receiving:manage` usam `release_email`. Quem pode liberar cada tipo de retenção está na [Segurança do agente](/docs/pt-br/agent-safety).

## Códigos de verificação

`GET /inboxes/{id}/codes/latest` responde o código de verificação ou link de acesso mais recente que a caixa recebeu, para o agente nunca precisar ler HTML:

```sh
curl "https://api.billionsend.com/inboxes/{id}/codes/latest?from=example.org&wait=30" \
  -H "Authorization: Bearer bs_..."
```

```json
{
  "object": "verification_code",
  "status": "found",
  "kind": "link",
  "code": null,
  "url": "https://app.example.org/verify?token=Qm9vdHN0cmFwLTQ4MjkxMw",
  "link_domain_matches_sender": true,
  "email_id": "155252fb-e93e-45ee-8c19-5080a929c28b",
  "from": "no-reply@example.org",
  "received_at": "2026-10-12T14:03:11.229Z",
  "sender_trust": "external"
}
```

- `kind` é `otp` (código em `code`) ou `link` (endereço em `url`, com `link_domain_matches_sender`).
- `from` restringe a um remetente; `wait` (0 a 50 segundos) espera um chegar; `max_age` (60 a 86.400 segundos, 600 por padrão) ignora códigos mais antigos; `since` ignora e-mails recebidos nesse horário ou antes, então passe o `received_at` de um código que você já usou para esperar o próximo.
- `status` é `found`, `none`, `ambiguous` (dois códigos igualmente prováveis, então nenhum é respondido) ou `timeout`. A resposta é sempre `200`.
- Os códigos nunca vêm de e-mails em quarentena, de remetentes que falharam na autenticação, nem de uma caixa com `extract_codes` desligado. Toda leitura fica registrada na atividade da caixa.

## Fluxo de eventos

`GET /inboxes/events` é um fluxo de eventos enviados pelo servidor (SSE) com tudo o que acontece nas suas caixas, no instante em que é confirmado. Os eventos têm os nomes dos eventos de webhook (`inbox.email.received`, `inbox.thread.created`, `inbox.draft.created`, `email.received` e os demais eventos `inbox.*`) e o `data` do payload do webhook. `GET /inboxes/{id}/events` transmite uma só caixa e termina quando ela é excluída ou expira.

```sh
curl -N "https://api.billionsend.com/inboxes/events?types=inbox.email.received" \
  -H "Authorization: Bearer bs_..." \
  -H "Accept: text/event-stream"
```

```text
retry: 1000

id: 812.40.1790000000
event: inbox.email.received
data: {"type":"inbox.email.received","created_at":"2026-11-15T09:20:30.131Z","inbox_id":"7eeb9517-aed7-40d7-ad65-500be42ed147","data":{"source":"system","inbox_id":"7eeb9517-aed7-40d7-ad65-500be42ed147","thread_id":"...","email_id":"...","email":{}}}

: keepalive
```

- Envie a chave num cabeçalho `Bearer`, como em toda requisição. O `EventSource` dos navegadores não consegue enviá-lo: use `fetch` e leia o corpo, ou qualquer cliente SSE que aceite cabeçalhos.
- `types` restringe o fluxo a alguns eventos, separados por vírgula; `/inboxes/{id}/events` ainda envia `inbox.deleted` e `inbox.expired`, os eventos que o encerram. Todo evento traz só metadados, como um webhook: sem corpo, código ou link. Leia a mensagem pelos endpoints de [recebimento](/docs/pt-br/receiving).
- **Retomada.** Todo evento tem um `id`. Um cliente que reconecta com `Last-Event-ID` (ou `?last_event_id=`) recebe, em ordem, o que perdeu antes dos eventos ao vivo. Os eventos ficam guardados por 24 horas; uma reconexão com um id mais antigo recebe antes um evento `stream.gap`, que significa que podem faltar eventos e que as listas devem ser lidas de novo.
- Sem `Last-Event-ID`, o fluxo começa sem reenvio. O servidor o fecha a cada 10 minutos, mais ou menos, e quando a API reinicia: reconecte com o último `id` que você viu. `retry: 1000` pede ao cliente que espere um segundo. Uma linha de comentário a cada 15 segundos impede que proxies fechem um fluxo parado.
- Uma chave da equipe inteira abre `/inboxes/events`. Uma chave restrita a um domínio, ou a uma caixa, abre `/inboxes/{id}/events` de uma caixa que ela alcança. Uma chave só de envio não abre fluxos.
- Um agente (uma chave restrita a uma caixa, ou uma conexão MCP) nunca recebe `inbox.email.quarantined`, nem ao vivo nem no reenvio, assim como nunca lê e-mail retido; pedi-lo em `types` dá `403 restricted_api_key`.
- Um fluxo fecha em poucos segundos quando a chave é revogada, quando a pessoa que criou a chave sai do time ou quando a caixa é excluída ou expira.
- Cada chave pode manter 5 fluxos ao mesmo tempo em cada processo da API e cada equipe 25; o seguinte responde `429 too_many_streams` com `retry-after`. Um fluxo para a equipe toda basta para a maioria dos agentes.

O `wait` de `/emails/receiving` e de `codes/latest` é acordado pelos mesmos eventos, então esperar não custa nada enquanto nenhum e-mail chega.

## Chaves de API restritas a uma caixa

Dê a cada agente uma chave que alcança só a caixa dele. Veja [Chaves de API](/docs/pt-br/api-keys).

```sh
curl -X POST "https://api.billionsend.com/api-keys" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "agente de pedidos",
    "permission": "full_access",
    "inbox_id": "7eeb9517-aed7-40d7-ad65-500be42ed147"
  }'
```

- Exige `permission: "full_access"` e não pode ter também um `domain_id`. Uma caixa tem no máximo 5 chaves ativas, fora do limite de 25 da equipe.
- A chave lê a caixa dela (conversas, e-mails, rascunhos, etiquetas, códigos, o fluxo de eventos e `/emails/receiving` limitado à caixa), responde, encaminha, escreve rascunhos e os envia, envia e-mails novos da própria caixa, e envia somente pelo endereço da caixa (`403 restricted_api_key` para outro `from`; `550 5.7.1` por SMTP).
- Todo o resto responde `403 restricted_api_key`: ela não altera configurações de segurança, não lista nem libera quarentena, não aprova rascunhos, não cria chaves e não alcança outra caixa.
- Ela para de funcionar quando a caixa expira, e excluir a caixa a revoga.

No painel, proprietários, administradores e desenvolvedores escolhem a caixa em **Restringir a uma caixa de entrada** ao criar a chave.

## Webhooks

Os eventos de caixa (`inbox.created`, `inbox.thread.created`, `inbox.email.received`, `inbox.email.sent`, `inbox.email.quarantined`, `inbox.expired`, os eventos `inbox.draft.*` e outros) vão só para endpoints que os citam, nunca para um endpoint inscrito em todos os eventos. Um endpoint pode ser limitado a algumas caixas com `inbox_ids`. `email.received` continua disparando para o e-mail de caixa depois de entregue. Payloads: [Webhooks](/docs/pt-br/concepts/webhooks).

## Atividade

Tudo o que acontece numa caixa fica registrado: envios e decisões das regras, recusas, rascunhos, aprovações, liberações, leituras de código, mudanças de segurança, exclusões e chaves. A aba **Atividade** da caixa lista isso com quem agiu: uma pessoa, uma chave de API ou um app conectado. As decisões guardam só códigos de motivo, nunca conteúdo, códigos nem endereços.

## Limites

| Limite | Valor |
| --- | --- |
| Caixas | 3 no Free, 25 no Starter, ilimitadas no Pro e no Scale. |
| Caixas criadas por hora | 10 no Free, 60 no Starter, 600 no Pro e no Scale. |
| E-mails por caixa | 200 mensagens aceitas por hora corrida numa caixa de agente, 2.000 numa caixa de pessoas. Acima disso, os remetentes recebem `452 4.2.2` e tentam de novo mais tarde. |
| Envios | `send_cap` destinatários por dia UTC. Uma caixa nova alcança destinatários novos aos poucos: 10 no primeiro dia de envio, depois 20, 40, 80, 160 e assim por diante, até o limite. |
| Destinatários por envio | 50 (`to`, `cc` e `bcc` juntos); 10 a partir de um endereço compartilhado. |
| Anexos por envio | 10 MiB decodificados no total; nenhum a partir de um endereço compartilhado. |
| Domínio compartilhado | 1.000 destinatários por dia UTC para todos os endereços compartilhados da sua equipe; uma caixa compartilhada sem uso há 90 dias é excluída. |
| Etiquetas | 100 por caixa. |
| Listas de segurança | 500 entradas na lista de permitidos, 50 endereços de responsáveis, 5 endereços em `forward_to`. |
| Chaves restritas a uma caixa | 5 ativas por caixa. |
| Análise | 200 mensagens por caixa por dia; acima disso, o e-mail que precisa de análise vai para a quarentena. |
| Espera | 50 segundos por requisição; 20 esperas ao mesmo tempo por equipe em cada processo da API. |
| Fluxos de eventos | 5 por chave de API e 25 por equipe ao mesmo tempo em cada processo da API; os eventos são reenviados por 24 horas. |
| Rascunhos e lixeira | Um rascunho pendente expira em 7 dias; uma conversa na lixeira é excluída após 30. |
| Retenção | O e-mail da caixa segue a retenção do e-mail recebido: 30 dias. |

As caixas em si não custam nada: o e-mail recebido conta uma vez por mensagem no seu limite de recebimento, nunca no seu volume de envio, como em [Recebimento](/docs/pt-br/receiving).

## Painel

**Caixas de entrada** na barra lateral lista as suas caixas nas abas **Todas**, **Agente** e **Pessoas**, com o que precisa de atenção: rascunhos para aprovar, conversas não lidas e mensagens em quarentena. Uma linha fixa **Todos os recebidos** abre todos os e-mails que os seus domínios receberam. A página de uma caixa tem quatro abas: **Conversas** (ler, responder e aprovar rascunhos ali mesmo), **Precisa de revisão** (rascunhos e quarentena), **Segurança e regras** e **Atividade**.

Qualquer membro pode trabalhar nas conversas de uma caixa, aprovar rascunhos e liberar a quarentena. Proprietários, administradores e desenvolvedores também podem criar, alterar e excluir caixas, mudar regras de segurança, criar chaves restritas a uma caixa, apagar e-mails recebidos e ligar o pega-tudo. Veja [funções da equipe](/docs/pt-br/team-roles).

## MCP

Os [clientes MCP](/docs/pt-br/mcp) trabalham com caixas sob três permissões: `receiving:read` (ler e-mails, esperar por eles, ler códigos, listar caixas, conversas, etiquetas e rascunhos, buscar conversas, ler as regras de segurança), `receiving:reply` (responder, encaminhar, enviar de uma caixa, escrever, enviar e excluir rascunhos, organizar conversas e etiquetas) e `receiving:manage` (criar, alterar e excluir caixas, listar e liberar a quarentena). Um cliente MCP sempre vê os e-mails como um agente: sem os retidos e com o texto das mensagens isolado como não confiável. Ele nunca aprova rascunhos, e `create_inbox` aceita `accept_from` e nenhuma outra configuração de segurança; ele nunca altera as regras de segurança de uma caixa.

## Notas da API

- Criar uma caixa ou um rascunho responde o objeto inteiro.
- `email_address` é opcional: omitido, a caixa ganha um endereço aleatório e permanente no domínio compartilhado.
- `kind` é `agent` por padrão, então uma caixa criada sem ele ganha as proteções de um agente.
- Não há agente hospedado: `GET /inboxes/{id}/agent` responde `instructions`, `tone` e `actions` vazios, e `PATCH /inboxes/{id}/agent` responde `422`.
- Ainda não há suporte para: `headers` personalizados em respostas, encaminhamentos e envios de rascunho, e anexos por `path` (URL remota). Cada um responde `422` a menos que o valor seja vazio.
- Uma resposta, encaminhamento ou envio de rascunho retido pelas regras da caixa responde `202` com o rascunho em vez de `200` com o e-mail: confira se `object` é `inbox_draft` antes de tratar o resultado como enviado.
- Erros das caixas: `403 inbox_send_policy`, `429 inbox_send_cap_reached`, `403 approval_required`, `403 email_quarantined` e `503 name_review_unavailable` (veja [Erros](/docs/pt-br/api-reference/basics)).
- Os eventos de webhook `inbox.*` são opt-in; `inbox.thread.assigned` e `inbox.thread.unassigned` não são enviados.
