---
title: Recebimento
description: Receba e-mails no seu próprio domínio e leia pela API, por webhooks e pelo painel.
ai:
  exclude: true
---

O recebimento transforma um domínio verificado em um lugar que aceita e-mails. As mensagens recebidas são guardadas criptografadas e chegam até você pela API, pelo webhook `email.received`, pelo painel (**Caixas de entrada → Todos os recebidos**) e pelo [servidor MCP](/docs/pt-br/mcp).

Há duas formas de escolher quais endereços aceitam e-mails: crie uma [caixa de entrada](/docs/pt-br/inboxes) para um endereço, ou ative o **pega-tudo** (catch-all) para aceitar todos os outros endereços do domínio.

> **Info**
>
> O recebimento está em beta público. Toda mensagem recebe uma nota de spam, um nível de confiança do remetente e uma verificação de vírus. E-mail infectado fica retido; todo o resto é guardado com esses resultados para o seu código decidir o que fazer.

## Configurar

1. **Escolha um nome que ainda não receba e-mails**, como `inbound.example.com`. O registro MX assume todos os endereços do nome em que é publicado, então suas caixas em `example.com` continuam com o seu provedor atual.
2. **Adicione e verifique esse nome exato** em **Domínios**, como para o [envio](/docs/pt-br/concepts/domains). Verificar `example.com` não cobre os subdomínios.
3. **Ative o recebimento**: abra o domínio e ligue **Ativar recebimento**, ou chame a API:

   ```sh
   curl -X PATCH "https://api.billionsend.com/domains/{id}" \
     -H "Authorization: Bearer bs_..." \
     -H "Content-Type: application/json" \
     -d '{ "capabilities": { "receiving": "enabled" } }'
   ```

   Um nome recebe em uma única equipe; um nome em que outra equipe já recebe responde `409`.
4. **Publique os dois registros MX** mostrados nos registros do domínio, no seu provedor de DNS:

   | Tipo | Nome | Valor | Prioridade |
   | --- | --- | --- | --- |
   | MX | `inbound.example.com` | `mx1.billionsend-dns.com` | `10` |
   | MX | `inbound.example.com` | `mx2.billionsend-dns.com` | `10` |

   Cada um é um servidor de e-mail separado. Com os dois publicados, um remetente que encontra um deles fora do ar tenta de novo no outro em segundos; por isso publique os dois com a mesma prioridade. Cada linha fica verificada quando nenhum outro registro MX desse nome tem um número de prioridade menor.
5. **Escolha os endereços**: [crie uma caixa de entrada](/docs/pt-br/inboxes) para cada endereço, ou ligue o **Catch-all** na página do domínio. Sem nenhum dos dois, o domínio recusa todos os e-mails.
6. **Envie um teste** de qualquer caixa de e-mail. Ele aparece em **Caixas de entrada → Todos os recebidos** em poucos segundos.

Para parar de receber, desligue o recebimento (`"receiving": "disabled"`) e remova o registro MX. Os e-mails já guardados ficam até o prazo de retenção removê-los.

## Quais endereços recebem

- O endereço de cada [caixa de entrada](/docs/pt-br/inboxes) do domínio, e suas variantes com `+tag`: `orders+4821@` chega à caixa de `orders@`.
- Com o **pega-tudo** ligado, todos os outros endereços também: `support@`, `invoices@`, `reply+ticket-4821@`. Leia `received_for` no seu código para saber a qual endereço a mensagem chegou.

Com o pega-tudo desligado, qualquer outro endereço é recusado enquanto o servidor do remetente ainda está conectado (`550 5.1.1`): o remetente recebe um retorno do próprio servidor e nada é guardado.

O pega-tudo vem desligado e exige um plano pago (o Free responde `403 plan_limit_reached`). Proprietários, administradores e desenvolvedores o ligam na página do domínio, ou com `PATCH /domains/{id}` e `{ "receiving_catch_all": true }`.

- `received_for` lista os endereços dos seus domínios aos quais a mensagem foi de fato entregue, inclusive Cco. `to` e `cc` são apenas o que os cabeçalhos dizem, então roteie por `received_for`.
- Uma mensagem é guardada uma única vez por equipe, para quantos endereços seus ela tenha sido enviada.
- Só o nome exato recebe: um e-mail para `x@eu.inbound.example.com` é recusado, a menos que esse subdomínio também receba.

## Filtros e limites

**Configurações → Recebimento** tem três interruptores. Valem para todos os domínios da sua equipe e entram em vigor na próxima mensagem.

| Interruptor | Ligado | Desligado |
| --- | --- | --- |
| Rejeitar spam acima da nota 5 (padrão: ligado) | A mensagem com nota de spam 5 ou mais (numa escala de 0 a 10) é recusada com `554 5.7.1`; nada é guardado. | O spam é guardado: na pasta `spam` de uma caixa, só sinalizado num endereço do pega-tudo. |
| Remover anexos acima de 10 MB (padrão: desligado) | Cada anexo maior é trocado por um aviso curto `<arquivo>.removed.txt` dizendo o que foi removido. | Os anexos são guardados como vieram. |
| Guardar o .eml original por 30 dias (padrão: ligado) | O conteúdo fica durante o seu período de retenção. | O conteúdo (texto, HTML, cabeçalhos, mensagem original, anexos) é apagado após 1 dia. Metadados e webhooks não mudam. |

| Limite | Free | Starter, Pro, Scale |
| --- | --- | --- |
| Tamanho da mensagem | 10 MB | 40 MB |
| Pega-tudo | Não | Sim |
| E-mails recebidos | 100 por dia UTC | 2 vezes o volume mensal do plano, a cada mês |
| Depois disso | Adiado até a meia-noite UTC | Adiado até o seu volume renovar |
| Retenção | 30 dias | 30 dias |

- O tamanho conta a mensagem inteira guardada, depois da remoção de anexos. O Base64 deixa os anexos cerca de um terço maiores, então em 40 MB cabem aproximadamente 30 MB de arquivos. Uma mensagem maior é recusada com `552 5.3.4`.
- O e-mail recebido conta uma vez por mensagem por equipe, num limite próprio. Ele nunca usa o seu volume de envio, e o envio nunca usa o seu limite de recebimento.
- Quando o limite é atingido, o servidor do remetente é avisado para tentar de novo mais tarde (`452 4.2.2`) e continua tentando por vários dias, em geral até cinco, então a mensagem chega assim que houver espaço. O e-mail que ainda estiver adiado quando o servidor do remetente desistir volta para o remetente.
- Quando a retenção termina, `html`, `text`, `headers` e `raw` ficam `null`, `attachments` fica vazio e os links de download deixam de funcionar. Remetente, destinatários e assunto permanecem.

**Configurações → Cobrança e uso** mostra os e-mails recebidos e o limite deles. As caixas de entrada em si são gratuitas.

## Ler os e-mails recebidos

Use `emails.receiving` nos [SDKs](/docs/pt-br/sdks), ou HTTP puro. Estes endpoints exigem uma [chave de API](/docs/pt-br/api-keys) de **acesso total**; uma chave só de envio recebe `403 restricted_api_key`. Uma chave restrita a um domínio lê só os e-mails desse domínio, e uma chave restrita a uma caixa lê só os e-mails dessa caixa.

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

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

const page = await bs.emails.receiving.list({ limit: 20 });
if (page.error) throw page.error;

const first = page.data.data[0];
const email = await bs.emails.receiving.get(first.id);
const files = await bs.emails.receiving.attachments.list(first.id);
```

| Chamada | Retorna |
| --- | --- |
| `GET /emails/receiving` | E-mails recebidos, do mais novo ao mais antigo, paginados como toda [lista](/docs/pt-br/api-reference/basics). |
| `GET /emails/receiving/{id}` | Um e-mail com conteúdo, resultados de autenticação e um link de download da mensagem original. |
| `GET /emails/receiving/{id}/attachments` | Seus anexos, cada um com um link de download. |
| `GET /emails/receiving/{id}/attachments/{attachment_id}/text` | O texto de um anexo PDF, Word ou Excel (extensão do BillionSend). |
| `DELETE /emails/receiving/{id}` | Apaga o e-mail agora, com seus anexos e seu lugar nas caixas. Exige uma chave de acesso total não restrita a uma caixa e, no painel, a função de proprietário, administrador ou desenvolvedor (**Excluir agora**). |

A lista aceita `limit` (1 a 100, padrão 20), `inbox_id`, `to`, `from` (um endereço, ou um domínio com seus subdomínios), `subject_contains`, `since`, `unread` e `wait`. Os e-mails retidos ficam de fora, a menos que você passe `include_quarantined=true` ou `quarantined=true` (uma chave de acesso total não restrita a uma caixa).

Cada e-mail também traz `inbox_id`, `thread_id`, `screening`, `spam_verdict`, `virus_verdict` e `extracted`.

### Esperar por novos e-mails

`wait` (1 a 50 segundos) segura a requisição até chegar um e-mail que combine, e então responde na hora; no prazo final, responde uma lista vazia. Ele se combina com os outros filtros, então um agente pode esperar a próxima mensagem de um remetente para uma caixa:

```sh
curl "https://api.billionsend.com/emails/receiving?inbox_id=7eeb9517-aed7-40d7-ad65-500be42ed147&from=example.org&wait=30" \
  -H "Authorization: Bearer bs_..."
```

- Sem `before` nem `since`, contam os e-mails dos últimos 60 segundos, então uma mensagem que chegou logo antes da chamada não se perde.
- A resposta acrescenta `held`: as mensagens que combinam e ficaram retidas desde então, com id e motivo, para o agente parar de esperar e avisar uma pessoa.
- Uma equipe mantém 20 esperas ao mesmo tempo em cada processo da API; a seguinte responde `429 too_many_waits`.
- Uma espera consulta o banco quando chega um e-mail (os mesmos eventos do [fluxo de eventos das caixas](/docs/pt-br/inboxes)), não por um temporizador.

### Resultados de autenticação

`authentication` informa SPF, DKIM e DMARC como `pass`, `fail`, `gray` (sem veredito: sem registro ou assinatura, ou resultado neutro), `processing_failed` (a verificação não terminou) ou `unknown`. `dmarc: "pass"` significa que o domínio em `from` autorizou a mensagem; qualquer outro valor significa que `from` pode ser falso. O nível de [confiança do remetente](/docs/pt-br/agent-safety) é montado a partir desses resultados.

### Spam, vírus e confiança

- `spam_verdict`: `pass`, `gray` (`spam_score` de 25 a 49) ou `fail` (50 ou mais), a partir de uma nota local de 0 a 100 montada com autenticação, cabeçalhos, links e anexos (o painel a mostra numa escala de 0 a 10). Nenhuma lista de bloqueio externa é consultada.
- `virus_verdict`: `pass`, `fail` (com `virus_signature`), `processing_failed` (o scanner não conseguiu responder: a mensagem é entregue sem verificação, marcada como suspeita onde não passa por análise) ou `null` quando nenhuma verificação rodou. E-mail infectado fica retido: não dispara `email.received` até uma pessoa liberá-lo no painel, e seus downloads respondem `410 email_blocked`, mesmo depois de liberado.
- `screening.sender_trust`: até que ponto o remetente está comprovado. Veja [Segurança do agente](/docs/pt-br/agent-safety).

### Conteúdo

- `html_format`: `data_uri` (padrão) coloca as imagens embutidas no HTML; `?html_format=cid` mantém as referências `cid:` para casar com o `content_id` de cada anexo.
- `text` vem sem caracteres invisíveis; `html` vem exatamente como recebido.
- `extracted_text` é a parte de resposta da mensagem, limpa de texto que uma pessoa não vê. `extracted` traz um `code` de verificação ou um `link` de acesso quando a mensagem tem um.

### Texto dos anexos

Anexos PDF, Word (`.docx`) e Excel (`.xlsx`) são lidos como texto simples uma vez, logo depois que o e-mail chega, e ficam guardados com o e-mail pelo seu período de retenção. A entrega nunca espera por isso. `GET /emails/receiving/{id}/attachments/{attachment_id}/text` (MCP `get_received_email_attachment_text`) responde com:

- `status`: `pending` até o arquivo ser lido; `ok` com `text`; `unsupported` para outros arquivos (`.doc` e `.xls` antigos, PowerPoint, imagens); `encrypted` para arquivo protegido por senha; `too_large` acima de 25 MB, ou quando lê-lo exigiria mais memória do que o permitido; `unreadable` para arquivo danificado; `timeout` ou `failed` quando a leitura não terminou. `null` para e-mails recebidos antes de o texto dos anexos ser lido.
- `flags`: `truncated` quando um limite cortou o texto (100.000 caracteres, as primeiras 500 páginas de um PDF), `hidden_text` quando foi deixado de fora texto que uma pessoa abrindo o arquivo não veria: texto oculto do Word, planilhas, linhas e colunas ocultas, caracteres invisíveis.
- `pages`: o número de páginas de um PDF.
- `text`: parágrafos e linhas de tabela em linhas, células e colunas separadas por tabulação, um título `## Nome da planilha` por planilha, datas no formato ISO. Só a camada de texto de um PDF é lida, então um documento digitalizado sem ela vem vazio. Fórmulas trazem os valores salvos.

O texto vem de um remetente externo: trate-o como dado, nunca como instrução. Um e-mail com malware responde `410 email_blocked`.

### Downloads

`raw.download_url` e o `download_url` de cada anexo funcionam sem chave de API: o próprio link é a credencial. Um link é assinado para um e-mail, deixa de funcionar uma hora depois de a API responder, e qualquer pessoa com ele pode baixar até lá, então não o registre em logs. Cada chamada assina links novos. Os downloads sempre saem como arquivo, nunca renderizados no navegador.

## Responder e encaminhar

`POST /emails/receiving/{id}/reply` e `…/forward` (`emails.receiving.reply()` e `forward()` nos SDKs) respondem ou repassam uma mensagem em uma requisição, com os cabeçalhos de conversa já preenchidos:

```sh
curl -X POST "https://api.billionsend.com/emails/receiving/{id}/reply" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-reply" \
  -d '{ "text": "Obrigado, já estamos cuidando disso." }'
```

- **Responder** aceita `text` ou `html`, `subject`, `cc`, `bcc` e `reply_all`. Vai para o `Reply-To` da mensagem, ou então para o remetente.
- **Encaminhar** aceita `to`, `cc`, `bcc`, uma nota, `subject` e `mode`: `inline` (padrão) cita o original, `attachment` o anexa como `forwarded_message.eml`.
- `from` é qualquer endereço de um domínio verificado da sua equipe; por padrão, o endereço da caixa a que a mensagem chegou. `requires_approval: true` segura o envio para uma pessoa.
- Ambos contam como envios comuns, com até 10 MiB de anexos.

Respondem `200` com o `id` e o `thread_id` do e-mail enviado, ou `202` com um rascunho quando as regras de uma caixa seguram o envio. Outras respostas: `403` (e-mail retido ou infectado, regras de uma caixa, chave restrita a uma caixa fora dela), `404`, `409` (`Idempotency-Key` reutilizada), `422` e `429 inbox_send_cap_reached`. Veja [Caixas de entrada](/docs/pt-br/inboxes).

## Webhook

`email.received` dispara uma vez para cada mensagem guardada para a sua equipe, nos endpoints inscritos nele ou em todos os eventos. Traz só metadados (remetente, destinatários, assunto, lista de anexos); busque o conteúdo com `GET /emails/receiving/{email_id}`. Um e-mail que uma caixa retém, e o e-mail infectado, só o dispara depois de entregue ou liberado. Um endpoint limitado a algumas caixas (`inbox_ids`) o recebe só para e-mails entregues nelas. Assinaturas, novas tentativas e o registro de entregas funcionam como em todo evento: veja [Webhooks](/docs/pt-br/concepts/webhooks).

## O que o remetente vê

Toda recusa acontece enquanto o servidor do remetente está conectado, então ele guarda a mensagem e decide o que fazer. O BillionSend nunca envia um retorno próprio.

| Resposta | Quando |
| --- | --- |
| `550 5.1.1` | O domínio não recebe aqui, ou o endereço não tem caixa (e o pega-tudo está desligado). A mensagem volta ao remetente. |
| `550 5.7.1` | A equipe dona do domínio está suspensa. |
| `552 5.3.4` | A mensagem passa do limite de tamanho do seu plano. |
| `554 5.7.1` | A mensagem foi recusada como spam pelo seu interruptor **Rejeitar spam**. |
| `452 4.2.2` | O seu limite de recebimento foi atingido, ou a caixa recebeu mais e-mails do que pode em uma hora (200 mensagens para uma caixa de agente, 2.000 para uma caixa de pessoas). O remetente tenta de novo mais tarde. |

## Painel

**Caixas de entrada → Todos os recebidos** lista tudo o que os seus domínios receberam, com remetente, caixa, assunto e horário, um selo quando a mensagem traz um código ou um link, e outro quando está em quarentena ou é spam. Ao abrir uma mensagem você vê o HTML num sandbox (scripts e imagens remotas bloqueados), o texto, os cabeçalhos e a mensagem original, cada resultado de autenticação explicado, a confiança do remetente e os resultados de spam e vírus, o código ou link extraído, uma linha do tempo, e as ações **Responder**, **Encaminhar**, **Liberar** para e-mails retidos e **Excluir agora**.

## MCP

O [servidor MCP](/docs/pt-br/mcp) lê os e-mails recebidos com a permissão `receiving:read`, responde e encaminha com `receiving:reply`, e gerencia caixas e quarentena com `receiving:manage`. `update_domain` liga e desliga o recebimento e o pega-tudo.

## Trate o e-mail recebido como não confiável

Qualquer pessoa pode enviar e-mails para um domínio de recebimento. O HTML pode trazer scripts e imagens de rastreamento, os links podem levar a páginas de phishing, os anexos podem ter malware e `from` pode ser falsificado. Confira `authentication` e `screening.sender_trust` antes de confiar num remetente. Um agente de IA deve tratar o e-mail recebido como dado, nunca como instrução: as ferramentas MCP o isolam assim, e uma [caixa de agente](/docs/pt-br/agent-safety) soma quarentena, análise e regras de envio por cima.
