Um API de e-mail de entrada recebe mensagens enviadas a um endereço ou domínio que você possui, faz o parse e entrega ao seu aplicativo como um POST HTTP estruturado. Em vez de rodar um servidor de e-mail e consultar uma caixa de entrada via IMAP, você aponta os registros MX do seu domínio para o provedor, e cada mensagem recebida chega ao seu endpoint com os cabeçalhos, corpo e anexos já parseados em JSON.
Como funciona o e-mail de entrada?
O roteamento começa pelo DNS. Você configura os registros MX de um domínio ou subdomínio (por exemplo, reply.yourapp.com) para apontar aos servidores de e-mail do provedor de entrada. Quando alguém envia uma mensagem para qualquer endereço nesse domínio, ela chega na infraestrutura do provedor, e não na sua. O provedor aceita a mensagem, faz o parse e envia uma requisição POST para a URL que você registrou, com o conteúdo já parseado.
Um payload parseado normalmente inclui remetente e destinatário, assunto, corpo em texto puro e HTML, o conjunto completo de cabeçalhos e quaisquer anexos (geralmente codificados em base64 ou referenciados por URL). Seu app lê esse JSON e age a partir dele, sem código SMTP ou IMAP para manter. O mecanismo de entrega é um webhook, então as mesmas regras se aplicam: responda com um 2xx rápido e depois processe a mensagem de forma assíncrona.
Para que é usado?
O e-mail de entrada transforma mensagens recebidas em eventos de aplicação. Padrões comuns incluem:
- Tratamento de respostas. Envie uma notificação a partir de
notifications@yourapp.come, quando o usuário responder, a resposta chega como um POST para que você possa vinculá-la de volta à conversa. - Abertura de tickets de suporte. E-mails para
support@yourapp.comse tornam um novo ticket, com o remetente e o corpo mapeados diretamente no seu help desk. - Parse para banco de dados. Recibos encaminhados ou e-mails estruturados são parseados e gravados em uma tabela, sem entrada manual.
- E-mail para ação. Uma mensagem para um endereço especial dispara um fluxo de trabalho: criar um registro, iniciar um job, postar em um canal.
Qual a diferença para o envio de e-mail?
Saída e entrada são trabalhos separados. Saída é o seu app entregando e-mail a destinatários via SMTP ou uma HTTP de envio API. Entrada é o inverso: remetentes externos entregando e-mail ao seu app. Uma integração de e-mail completa geralmente faz ambos, enviando notificações e recebendo as respostas de volta, mas eles são configurados de forma independente e o lado de entrada é o que depende dos seus registros MX.
Por que não consultar uma caixa de entrada via IMAP?
Você pode rodar um poller IMAP em uma caixa de entrada real, mas isso tem um custo contínuo. Você gerencia credenciais, decide com que frequência consultar (o que adiciona latência e conexões ociosas), faz o parse de MIME bruto por conta própria e rastreia quais mensagens já foram processadas. Um API de entrada elimina a maior parte disso: o provedor faz o parse do MIME, envia cada mensagem uma única vez como JSON limpo e você reage em tempo quase real. Para uma comparação dos protocolos subjacentes, veja SMTP vs. IMAP.
Perguntas frequentes
Quais alterações de DNS são necessárias?
Você configura os registros MX do domínio ou subdomínio no qual deseja receber e-mails para apontar ao seu provedor de entrada. Após a propagação, e-mails para qualquer endereço nesse domínio fluem para o provedor, que faz o parse e envia um POST ao seu endpoint. Usar um subdomínio dedicado mantém o roteamento de entrada separado do e-mail do seu domínio principal.
Como os anexos são tratados?
O payload parseado inclui os anexos, geralmente codificados em base64 inline ou como URLs que você busca separadamente. Seu handler decodifica ou faz o download deles e os armazena onde você guarda seus arquivos. Anexos maiores normalmente são referenciados por URL para manter o payload pequeno.
E-mail de entrada é o mesmo que um webhook?
A entrega usa um webhook: o provedor envia ao seu app um POST HTTP para cada mensagem. A diferença é que o payload é um e-mail completamente parseado, e não um evento genérico. Trate-o como qualquer webhook: verifique-o, responda rapidamente e processe de forma assíncrona.
Para ver como o Bird lida com as duas direções do e-mail, comece pela visão geral do produto de e-mail e pelo guia de eventos de e-mail, que cobre o modelo de entrega de eventos no qual o seu handler de entrada se baseia.