Demo: sistema de e-mail baseado no Meteor com geolocalização e rastreamento de UA

Em janeiro anunciamos que fizemos uma parceria com o Meteor para alimentar o back-end de e-mail que acompanha a plataforma Meteor. Para ver um exemplo, confira este formulário de inscrição em evento sobre o qual publicamos recentemente, mas hoje queremos demonstrar outro exemplo da integração Meteor+Mailgun.

Algumas semanas atrás, lançamos novos parâmetros para os nossos webhooks para obter informações de geolocalização e user-agent dos seus e-mails sem precisar analisar as strings de UA e usar bibliotecas de pesquisa de IP. Achamos que seria divertido criar um pequeno aplicativo no Meteor para mostrar como é fácil consumir esses novos parâmetros.

Clique na demo abaixo para vê-la em ação e baixar o código-fonte do aplicativo no GitHub para que você possa explorá-lo e criar o seu próprio aplicativo ou relatório. Depois de explorar a demo, volte aqui para detalharmos como a desenvolvemos.

Você pode enviar e-mails com o Mailgun via SMTP padrão ou com a API HTTP do Mailgun. Se você quer apenas uma funcionalidade simples de envio por SMTP no seu aplicativo Meteor, comece adicionando o pacote de e-mail ao seu projeto.

>> meteor add email

Após executar esse comando, você terá uma conta padrão do Mailgun configurada automaticamente, e o Meteor definirá de forma automática a variável de ambiente MAIL_URL que armazena a configuração SMTP. (Confira a documentação de e-mail no site do Meteor aqui. Como mencionado no último parágrafo, você pode testar o envio mesmo sem adicionar o pacote de e-mail: por padrão, os e-mails serão exibidos diretamente no console).

Para esta demo, vamos além do envio básico de e-mail, por isso usamos uma conta do Mailgun diretamente com a API HTTP (aliás, com a API, o Mailgun monta o MIME no lado do servidor, o que torna o processo um pouco mais fácil, mesmo em envios simples de e-mail).

Para começar, pegue a sua chave de API no painel de controle do Mailgun. Ela aparecerá assim que você fizer o login.

A chamada para a API será feita com uma simples solicitação HTTP POST. Você precisará adicionar o pacote http do Meteor ao seu projeto.

>> meteor add http

Depois que o pacote http for instalado, você poderá executar qualquer solicitação HTTP: GET, POST, PUT, DELETE etc. no seu aplicativo.

Indo direto à parte mais interessante: abaixo está um exemplo de como você pode enviar um e-mail com o Mailgun via API:

                                

                                    Meteor.http.post('https://api.mailgun.net/v2/your-api-domain/messages',  
    {auth:"api:" + process.env.MAILGUN_API_KEY,
    params: {"from":"Dev McCool  ",
                     "to":[to],
                      "subject":"Behold: the power of Meteor and Mailgun",
                      "html":”A <b>bold</b> greeting goes here”,
                      "h:X-Mailgun-Variables":JSON.stringify({tracking_id:my_tracking_var}),
                      "o:tracking":'True’ }}, function(error, result) {
                      //handle error, result (should be 200 OK)
                     }
           }
                                
                            

Vamos analisar alguns detalhes aqui.

Como é possível notar, estamos definindo um cabeçalho de autenticação com essa solicitação usando uma variável de ambiente chamada MAILGUN_API_KEY. Ainda não é possível definir variáveis de ambiente na plataforma de hospedagem do Meteor (por exemplo, meteor deploy). Porém, se você estiver executando o seu aplicativo Meteor no Heroku ou na sua própria configuração, é uma boa ideia manter credenciais como a sua chave de API seguras em uma variável de ambiente. Se quiser definir uma variável de ambiente com o Meteor, basta fazer o seguinte:

process.env['MAILGUN_API_KEY'] = "my-mailgun-key";

Observe também que estamos adicionando alguns valores personalizados de rastreamento aqui.

• Definimos a opção de rastreamento como “true” para avisar ao Mailgun que deve disparar o webhook quando o e-mail for aberto.
• Definimos um valor JSON no campo de cabeçalho X-Mailgun-Variable. Isso demonstra o poder dos webhooks: podemos armazenar detalhes importantes ou valores exclusivos nesse campo de cabeçalho e recuperá-los quando o Mailgun disparar o webhook para o nosso servidor.

Neste exemplo específico, o envio do e-mail é acionado por um simples botão em HTML no lado do cliente. Agrupamos a funcionalidade de envio de e-mail em um método do Meteor, permitindo o acesso a partir do cliente. Veja o código de envio de e-mail aqui.

Lembre-se de manter informações importantes, como as credenciais da API, na pasta do servidor do seu aplicativo Meteor. Os arquivos na pasta do servidor não são enviados para o cliente. No entanto, outros arquivos, seja na pasta do cliente ou na raiz da pasta do aplicativo, podem acabar chegando ao navegador do cliente.

Quando o Mailgun detectar que o nosso e-mail foi aberto, enviará uma solicitação POST para nós. Como qualquer convidado, queremos que o webhook se sinta bem-vindo e saiba que chegou ao destino certo: nada de erros 404 aqui! O roteamento no lado do servidor ainda não está integrado ao Meteor, mas não se preocupe: graças à flexibilidade da plataforma, podemos adicionar uma rota simples para o webhook do Mailgun sem precisar desmontar nada. Há um pouco mais de código envolvido na configuração de uma rota no lado do servidor:

                                

                                    if (Meteor.isServer) {

  var app = __meteor_bootstrap__.app
  var connect = Npm.require('connect');
  var Fiber = Npm.require('fibers');
  var crypto = Npm.require('crypto');

  var router = connect.middleware.router(function(route)
  {
    route.post('/mailgun/receive', function(req, res)
    {
      var raw_post_body = "";
      var post_data = [];

      req.on('data', function (chunk) {
        raw_post_body += chunk.toString();
      });

      req.on('end', function () {
          pairs = raw_post_body.split('&');
          for(var i = 0; i < pairs.length; i++) {
            kv = pairs[i].split('=');
            post_data[kv[0]]=decodeURIComponent((kv[1]+'').replace(/+/g, '%20'));
          }

          //Verify sender is Mailgun
          var sig = crypto.createHmac('sha256', process.env.MAILGUN_API_KEY).update(post_data['timestamp']+post_data['token']).digest('hex');
          if(sig !== post_data['signature']) {
            res.writeHead(403);
            res.end();
          }
          else {
            Fiber(function() {
                Meteor.call("publishGeo", post_data);
                res.writeHead(200);
                res.end();
            }).run();
          }
      });
    });
  });

  app.use(router);

                                
                            

Mais ou menos na metade, você verá o trecho onde realizamos um rápido cálculo HMAC para confirmar a identidade do remetente. O Mailgun fornece um token de assinatura com cada webhook, e podemos verificar a validade dessa assinatura fazendo o hash do token fornecido e do carimbo de data e hora com a nossa chave de API. Não é um requisito obrigatório, mas apenas uma boa prática para qualquer aplicativo voltado ao público. É muito simples fazer isso utilizando o método HMAC encontrado na biblioteca crypto.

Com essa rota configurada e ativada no nosso servidor, podemos preparar o lado do Mailgun para os nossos webhooks.

Se você fizer login no Mailgun, verá a aba de rastreamento na parte superior do seu painel. Na parte inferior da página de rastreamento, há um campo para inserir o destino das solicitações POST que o Mailgun enviará sempre que um e-mail for aberto.

Neste aplicativo de demonstração, atribuímos um ID exclusivo a cada sessão de navegador, o qual incluímos na chamada da API do Mailgun (naquele cabeçalho HTTP X-Mailgun-Variables que enviamos antes). Quando o webhook de abertura retornar, poderemos inspecionar não apenas os detalhes de geolocalização, mas também analisar o código do ID de sessão exclusivo. É assim que saberemos a qual sessão de navegador o webhook pertence, permitindo exibir a localização correta no mapa.

Graças ao poder do framework do Meteor, o navegador (o cliente) pode observar qualquer alteração no conjunto de dados dos webhooks recebidos. Com o evento Collection “added” no cliente, o cliente é atualizado imediatamente ao adicionarmos outro evento de webhook no nosso banco de dados. Dentro do evento “added”, só precisamos gerar um marcador de localização do Google Maps usando os valores de cidade, região e país contidos no webhook. Aqui também verificaremos o ID exclusivo em relação ao ID de sessão atual. Se eles corresponderem, esse marcador será posicionado na frente do mapa (com z-index) com um ícone vermelho.

A última parte do código no lado do cliente envolve garantir que cada marcador no mapa tenha um pop-up com outros detalhes do navegador que o Mailgun também inclui nos dados do webhook. Os webhooks de rastreamento do Mailgun também incluem dados úteis, como o sistema operacional, qual cliente de e-mail foi usado para abrir/ler a mensagem e o tipo de dispositivo (ótimo para analisar o uso móvel em relação ao desktop!).

É isso: o seu aplicativo Meteor agora está pronto para receber webhooks de rastreamento e de abertura do Mailgun com segurança e confiabilidade.

Para ver tudo em ação, acesse o site da demo e o código-fonte no GitHub.

Autor: The Sinch Mailgun team The Sinch Mailgun team shares news, best practices, and strategies to take your products and apps to the next level using email. Subscribe to our newsletter to get all the articles in your inbox!