Recebimento
Receba e-mails no seu próprio domínio e leia pela API, por webhooks e pelo painel.
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.
Há duas formas de escolher quais endereços aceitam e-mails: crie uma caixa de entrada para um endereço, ou ative o pega-tudo (catch-all) para aceitar todos os outros endereços do domínio.
Configurar
-
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 emexample.comcontinuam com o seu provedor atual. -
Adicione e verifique esse nome exato em Domínios, como para o envio. Verificar
example.comnão cobre os subdomínios. -
Ative o recebimento: abra o domínio e ligue Ativar recebimento, ou chame a API:
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. -
Publique os dois registros MX mostrados nos registros do domínio, no seu provedor de DNS:
Tipo Nome Valor Prioridade MX inbound.example.commx1.billionsend-dns.com10MX inbound.example.commx2.billionsend-dns.com10Cada 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.
-
Escolha os endereços: crie uma caixa de entrada 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.
-
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 do domínio, e suas variantes com
+tag:orders+4821@chega à caixa deorders@. - Com o pega-tudo ligado, todos os outros endereços também:
support@,invoices@,reply+ticket-4821@. Leiareceived_forno 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_forlista os endereços dos seus domínios aos quais a mensagem foi de fato entregue, inclusive Cco.toeccsão apenas o que os cabeçalhos dizem, então roteie porreceived_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,headerserawficamnull,attachmentsfica 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, ou HTTP puro. Estes endpoints exigem uma chave de API 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.
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. |
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:
curl "https://api.billionsend.com/emails/receiving?inbox_id=7eeb9517-aed7-40d7-ad65-500be42ed147&from=example.org&wait=30" \
-H "Authorization: Bearer bs_..."
- Sem
beforenemsince, 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), 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 é montado a partir desses resultados.
Spam, vírus e confiança
spam_verdict:pass,gray(spam_scorede 25 a 49) oufail(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(comvirus_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) ounullquando nenhuma verificação rodou. E-mail infectado fica retido: não disparaemail.receivedaté uma pessoa liberá-lo no painel, e seus downloads respondem410 email_blocked, mesmo depois de liberado.screening.sender_trust: até que ponto o remetente está comprovado. Veja Segurança do agente.
Conteúdo
html_format:data_uri(padrão) coloca as imagens embutidas no HTML;?html_format=cidmantém as referênciascid:para casar com ocontent_idde cada anexo.textvem sem caracteres invisíveis;htmlvem exatamente como recebido.extracted_texté a parte de resposta da mensagem, limpa de texto que uma pessoa não vê.extractedtraz umcodede verificação ou umlinkde 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:pendingaté o arquivo ser lido;okcomtext;unsupportedpara outros arquivos (.doce.xlsantigos, PowerPoint, imagens);encryptedpara arquivo protegido por senha;too_largeacima de 25 MB, ou quando lê-lo exigiria mais memória do que o permitido;unreadablepara arquivo danificado;timeoutoufailedquando a leitura não terminou.nullpara e-mails recebidos antes de o texto dos anexos ser lido.flags:truncatedquando um limite cortou o texto (100.000 caracteres, as primeiras 500 páginas de um PDF),hidden_textquando 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 planilhapor 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:
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
textouhtml,subject,cc,bccereply_all. Vai para oReply-Toda mensagem, ou então para o remetente. - Encaminhar aceita
to,cc,bcc, uma nota,subjectemode:inline(padrão) cita o original,attachmento anexa comoforwarded_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: truesegura 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.
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.
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 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 soma quarentena, análise e regras de envio por cima.