Automatizando o monitoramento da infraestrutura de e-mail com os webhooks de eventos do Mailgun e o Datadog

Você já configurou alertas de preços de ações? Em vez de verificar constantemente, você recebe uma notificação quando a ação atinge um determinado preço. É exatamente assim que os webhooks funcionam: em vez de buscar atualizações repetidamente, o sistema receptor é notificado automaticamente pelo remetente quando um evento específico ocorre.

Com os webhooks de eventos do Mailgun, você pode lidar com eventos relacionados a e-mail em tempo real. Ao configurá-los no painel de controle do Mailgun, você pode disparar solicitações HTTP POST para endpoints de API especificados sempre que eventos de e-mail importantes ocorrerem. Você pode monitorar entregas, aberturas e reclamações de spam em tempo real para acompanhar o desempenho e resolver problemas instantaneamente. Os webhooks também permitem automação, gatilhos, novas tentativas, atualizações de CRM e tratamento de cancelamentos de inscrição assim que um evento de e-mail ocorre — tudo isso sem intervenção manual.

Neste artigo, você aprenderá a usar os webhooks do Mailgun para monitorar seus eventos de e-mail.

Os webhooks são uma forma leve de os aplicativos enviarem dados de eventos em tempo real. Eles permitem que um sistema (o remetente) envie uma solicitação HTTP para outro sistema (o receptor) quando um evento específico ocorre. Em vez de o receptor buscar atualizações constantemente, o remetente envia os dados automaticamente.

Os webhooks do Mailgun notificam seu aplicativo quando eventos de e-mail ocorrem — como entregas, devoluções ou aberturas — permitindo o processamento de eventos assim que eles acontecem. Por exemplo, se você estiver enviando e-mails promocionais e quiser rastrear quando clientes clicarem em um link, os webhooks do Mailgun poderão notificar você automaticamente. Quando um cliente clica em um link dentro do e-mail, o Mailgun detecta essa ação e envia imediatamente um webhook para seu servidor com detalhes como o e-mail do destinatário, o URL clicado e a data e hora:

{ "event": "clicked", "recipient": "customer@example.com", "url": "https://yourstore.com/special-offer", "timestamp": 1739373700 }

Seu sistema pode, então, marcar o cliente como “interessado” e disparar um e-mail de acompanhamento ou designar alguém da equipe de vendas para interagir com esse cliente. Esse rastreamento em tempo real ajuda as empresas a medir o engajamento e a responder rapidamente a possíveis leads.

O Mailgun dispara webhooks para os seguintes eventos de e-mail: abertura, clique, cancelamento de inscrição, devolução (devoluções permanentes e devoluções temporárias), falha e entrega. Para saber mais sobre os webhooks do Mailgun, confira este guia.

Os webhooks do Mailgun permitem rastrear vários eventos de e-mail. Integrá-los a uma ferramenta de monitoramento como o Datadog ajuda a visualizar e gerenciar os dados em tempo real. Você também pode configurar alertas para eventos importantes, como cliques (indicando possíveis leads) ou devoluções e falhas de entrega — permitindo uma resposta rápida quando necessário.

Antes de iniciar este tutorial, verifique se você tem o seguinte:

• Uma conta do Mailgun para enviar e-mails pela API do Mailgun. Se você não tiver uma conta, siga este guia de início rápido para configurar uma gratuitamente.
• Uma conta do Datadog para processar eventos de webhook do Mailgun e configurar alertas. Se você não tiver uma conta, uma avaliação gratuita será suficiente para este tutorial.
• curl, uma ferramenta de linha de comando para enviar e-mails com a API do Mailgun.

Para começar, faça login na sua conta do Mailgun e anote seu domínio de envio, junto com sua região, no painel do Mailgun. Se você estiver usando um plano gratuito, verá um domínio de sandbox, que será usado no endpoint de API e também no endereço de e-mail “from” ao enviar e-mails pela API do Mailgun. O domínio de sandbox segue o formato sandbox.mailgun.org, desta forma:

Observação: se você quiser usar seu próprio domínio de e-mail personalizado para enviar e-mails pelo Mailgun, precisará de um plano pago. O plano gratuito oferece suporte apenas a um domínio sandbox e limita o envio de e-mails a até cinco destinatários autorizados.

Para monitorar o engajamento dos destinatários, você precisa habilitar o rastreamento para o seu domínio do Mailgun.

Acesse Enviar > Envio > Configurações de domínio na sua conta do Mailgun. Na seção Rastreamento, verifique se as opções Rastreamento de cliques, Rastreamento de aberturas e Cancelamentos de assinatura estão ativadas:

Em seguida, crie uma chave de API na página de segurança de API, acessível por meio de um menu suspenso abaixo do seu nome, no canto superior direito. Você a usará para configurar a integração do Datadog com o Mailgun:

Assim que tiver sua chave de API do Mailgun, faça login na sua conta do Datadog e acesse Integrações pelo painel de navegação à esquerda (quase no final).

Na página de integrações, use a barra de pesquisa na parte superior para encontrar a integração com o Mailgun:

Clique em Mailgun e acesse a guia Configurar. Role para baixo até a seção Contas do Mailgun e clique em Adicionar nova. Insira seu domínio do Mailgun, a região e a chave de API. Depois, salve suas configurações.

Em seguida, na seção Coleta de logs, você precisa configurar um URL de endpoint para o Mailgun encaminhar dados de eventos como logs para o Datadog. Os webhooks do Mailgun exigem esse URL para publicar dados de eventos.

Para gerar o URL do webhook, selecione uma chave de API do Datadog existente (uma é criada por padrão) ou crie uma no pop-up de configuração, conforme abaixo:

Isso gera um URL de entrada personalizado com sua chave de API do Datadog, semelhante a este:
https://http-intake.logs.us5.datadoghq.com/api/v2/logs?dd-api-key=&ddsource=mailgun
Copie e salve esse URL: você vai precisar dele ao configurar os webhooks do Mailgun. Depois, feche o pop-up da integração com o Mailgun.

Na sua conta do Mailgun, acesse Enviar > Envio > Webhooks.

Na página de webhooks, clique em Adicionar webhook no canto superior direito. Escolha o tipo de evento que deseja rastrear, cole o URL de entrada personalizado que você gerou no Datadog na etapa anterior e clique em Criar webhook para salvar. Repita esse processo para criar três webhooks separados para Mensagens entregues, Aberturas e Cliques:

Agora, sempre que um desses eventos ocorrer, o Mailgun notificará automaticamente o URL do Datadog com os dados de evento relevantes.

O Mailgun permite enviar e-mails usando suas APIs. Você pode usar a ferramenta curl no seu terminal para enviar um único e-mail com o seguinte comando:

                                

                                    curl -s --user 'api:YOUR_API_KEY' \

https://api.mailgun.net/v3/YOUR_DOMAIN_NAME/messages \

-F from='User Name ' \

-F to=recipient@example.com \

-F subject="Exclusive 40% discount..." \

--form-string html='As a valued customer, we're excited to offer you an exclusive 40% discount on <a href="https://example.com/awesome-product">Our Awesome Product</a>. Grab it now!' \

-F o:tracking-opens="yes"
                                
                            

Substitua YOUR_API_KEY por sua chave de API do Mailgun e YOUR_DOMAIN_NAME por seu domínio do Mailgun. Isso autentica sua solicitação e garante que o Mailgun saiba que o e-mail está sendo enviado por um usuário autorizado.

Lembre-se do seguinte:

• O campo from precisa conter um endereço de e-mail válido do seu domínio do Mailgun.
• O campo to pode conter o endereço de e-mail de qualquer destinatário se você tiver um plano pago. No plano gratuito, ele deve ser um dos seus destinatários autorizados.
• A opção o:tracking-opens="yes" instrui o Mailgun a rastrear eventos de abertura do e-mail.

A mensagem em HTML também contém um link, e o Mailgun rastreia se o destinatário clica nele (acionando um gatilho de evento de clique).

Após a solicitação curl ser executada com êxito, o Mailgun responderá com uma mensagem como esta:

{"id":"@.mailgun.org","message":"Queued. Thank you."}

Para testar, experimente enviar e-mails para alguns destinatários diferentes.

Para monitorar o engajamento dos e-mails, faça login na sua conta do Datadog e acesse a seção Dashboards no painel de navegação à esquerda. Use a barra de pesquisa na parte superior para procurar e selecionar Visão geral do Mailgun.

O Datadog oferece um painel pronto que mostra eventos importantes de e-mail, como entregas, aberturas, devoluções e cliques em tempo real, ajudando a monitorar o desempenho dos e-mails em instantes:

O painel exibe as principais métricas, como a quantidade de e-mails entregues, e-mails abertos e links clicados. Ele também oferece outras análises úteis, todas com base nos dados de eventos recebidos dos webhooks do Mailgun.

Digamos que você queira capturar leads de sua campanha de e-mail rastreando todos que clicam em um link nela. Em vez de verificar constantemente o painel, seria melhor receber uma notificação por e-mail sempre que ocorrer um clique.

O Datadog permite configurar monitores que acionam alertas automaticamente com base nos eventos de webhook do Mailgun. Veja como você pode criar um monitor baseado em logs no Datadog que escuta os eventos clicked do Mailgun:

No painel de navegação à esquerda, clique em Monitores e, em seguida, em Novo monitor. Na lista de tipos de monitor, selecione Logs. Em seguida, clique em Configurar monitor de logs no canto inferior direito. Insira a seguinte consulta de pesquisa:

source:mailgun @evt.name:clicked

Isso vai filtrar os logs do Mailgun para considerar apenas os eventos clicados.

Escolha uma janela de tempo de avaliação, como cinco minutos ou qualquer intervalo adequado com base na frequência com que deseja verificar os cliques.

Na seção Definir condições do alerta, defina o gatilho de quando o valor avaliado estiver acima do limite. No campo Limite de alerta, defina a condição como maior que zero. Mantenha os demais valores inalterados. Isso garante que o monitor seja acionado quando um evento de clique for detectado no período de avaliação selecionado de cinco minutos.

Na seção Configurar notificações e automações, defina o título como “Alerta de lead: clique no link da campanha” e a mensagem do monitor da seguinte forma:

{{#is_alert}} Um lead em potencial interagiu com a sua campanha de e-mail promocional.

**Detalhes do lead:**

– Destinatário: {{log.attributes.usr.email}} – Carimbo de data/hora: {{log.timestamp}} – Link clicado: {{log.attributes.event-data.url}}

Considere fazer um acompanhamento e atualizar seu CRM.

—

Essa notificação é gerada pela integração com o Mailgun e o Datadog.

@ {{/is_alert}}

O bloco {{#is_alert}}...{{/is_alert}} que o envolve garante que essa mensagem seja enviada apenas quando o monitor for acionado (quando um clique for detectado), e não em outro caso de recuperação. Os valores nos blocos {{...}} contêm detalhes a partir dos dados do evento correspondente.

No campo @ Adicionar menção, insira os endereços de e-mail que receberão essa notificação, como os da equipe de CRM.

Por fim, revise a configuração do monitor e clique em Criar para finalizar.

Esse monitor vai acionar o alerta sempre que um evento de clique de webhooks do Mailgun for detectado em seus logs do Datadog. Seus endereços de e-mail de notificação receberão uma mensagem com os detalhes do lead. Essa configuração automatiza a detecção de leads das suas campanhas de e-mail sem precisar monitorar os painéis de forma manual.

Com tudo configurado, é hora de testar como os webhooks do Mailgun e o Datadog trabalham juntos para alertar você quando ocorre um evento de clique.

Abra um dos e-mails de teste que você enviou antes usando o comando curl e clique no link dentro dele para simular um destinatário interagindo com sua campanha.

O Mailgun detectará o evento de clique e acionará o webhook, enviando os dados de evento para o Datadog como uma entrada de log.

Como seu monitor está configurado para observar eventos de cliques, o Datadog avaliará a condição e acionará um alerta por e-mail contendo informações importantes sobre o lead, como o e-mail do destinatário, o carimbo de data/hora e o URL clicado.

Este é um e-mail de alerta enviado por esse monitor do Datadog:

Esse sistema totalmente automatizado não apenas rastreia o engajamento dos e-mails, mas também alerta você em tempo real quando um lead em potencial interage com a sua campanha do Mailgun. Da mesma forma, você pode automatizar as notificações para eventos de e-mail, como devoluções e falhas, para suas equipes de SRE.

Caso não queira mais rastrear um evento de e-mail específico, exclua o webhook correspondente no Mailgun.

Basta acessar Enviar > Envio > Webhooks na sua conta do Mailgun, localizar o evento que você deseja parar de rastrear e clicar em Excluir ao lado dele. O sistema vai pedir que você confirme a exclusão. Após a confirmação, o webhook será excluído, e o Mailgun vai parar de enviar dados de eventos referentes a esse tipo específico ao seu endpoint.

Neste tutorial, você aprendeu como os webhooks do Mailgun podem enviar dados de eventos para várias interações de e-mail, como entregas, aberturas, cliques, reclamações de spam e falhas. Você explorou como integrar esses webhooks ao Datadog para criar um sistema automatizado para monitorar o engajamento dos e-mails e receber notificações.

Isso ajudou? Não se esqueça de assinar a nossa newsletter para receber atualizações sobre conteúdos de tutoriais, além de notícias sobre e-mail e entregabilidade da nossa equipe especialista!

Autor: Manish Hatwalne Manish, with over 20 years of diverse coding experience, wears two hats: coder by day, writer by night. His knack lies in demystifying complex concepts and translating "geek speak" into everyday language.