Pular para o conteúdo
Esc
↑↓navegar↵abrir⌘Jpré-visualizar
Nesta página

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

  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. 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:

    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 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 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, 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 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), 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_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.

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:

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.

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.

Esta página foi útil?