Démo : application d’emailing basée sur Meteor avec géolocalisation et suivi du UA

En janvier nous avons annoncé notre partenariat avec Meteor pour propulser le back-end d’email fourni avec la plateforme Meteor. Pour voir un exemple, consultez ce formulaire d’inscription à un événement dont nous avons parlé récemment sur le blog, mais aujourd’hui nous voulons vous faire la démo d’un autre exemple d’intégration de Meteor+Mailgun.

Il y a quelques semaines, nous avons déployé de nouveaux paramètres pour nos webhooks afin de récupérer les informations de géolocalisation et de user-agent pour vos emails sans avoir à analyser les chaînes UA ni à utiliser de bibliothèques de recherche d’IP. Nous avons pensé qu’il serait amusant de créer une petite application sur Meteor pour montrer à quel point il est facile d’utiliser ces nouveaux paramètres.

Cliquez sur la démo ci-dessous pour la voir en action et télécharger le code source de l’application depuis GitHub pour pouvoir l’explorer et créer votre propre application ou rapport. Après avoir testé la démo, revenez ici et nous vous expliquerons plus en détail comment nous l’avons conçue.

Vous pouvez envoyer des emails avec Mailgun via le standard SMTP ou avec l’API HTTP de Mailgun. Si vous souhaitez simplement une fonctionnalité d’envoi SMTP classique dans votre application Meteor, commencez par ajouter le package email à votre projet.

>> meteor add email

Après avoir exécuté cette commande, un compte Mailgun par défaut sera automatiquement configuré et Meteor définira automatiquement la variable d’environnement MAIL_URL qui stocke la configuration SMTP. (Consultez la documentation sur l’email sur le site de Meteor ici. Comme mentionné dans le dernier paragraphe, vous pouvez tester l’envoi même sans ajouter le package email : par défaut, les emails s’afficheront directement dans la console).

Pour cette démo, nous allons aller plus loin que le simple envoi d’emails, nous utilisons donc directement un compte Mailgun et l’API HTTP (d’ailleurs, avec l’API, Mailgun assemble le type MIME côté serveur, c’est donc un peu plus simple à gérer, même pour un simple envoi d’email).

Pour commencer, récupérez votre clé API depuis le panneau de configuration de Mailgun ; vous la verrez lors de votre connexion.

L’API sera appelée via une simple requête HTTP POST. Vous devrez ajouter le package http de Meteor à votre projet.

>> meteor add http

Une fois le package http installé, vous pouvez effectuer n’importe quelle requête HTTP (GET, POST, PUT, DELETE, etc.) dans votre application.

Passons aux choses sérieuses : voici un exemple de la manière dont vous pouvez envoyer un email avec Mailgun via l’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)
                     }
           }
                                
                            

Passons en revue quelques détails.

Vous pouvez voir que nous configurons un en-tête d’authentification avec cette requête en utilisant une variable d’environnement appelée MAILGUN_API_KEY. Vous ne pouvez pas encore définir de variables d’environnement sur la plateforme d’hébergement Meteor (par ex. meteor deploy), mais si vous exécutez votre application Meteor sur Heroku ou sur votre propre infrastructure, il est conseillé de conserver les identifiants comme votre clé API en toute sécurité dans une variable d’environnement. Si vous souhaitez définir une variable d’environnement avec Meteor, procédez comme suit :

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

Remarquez également que nous ajoutons ici des valeurs de suivi personnalisées.

• Définir l’option de suivi sur « true » pour indiquer à Mailgun de déclencher le webhook à l’ouverture de l’email.
• Définir une valeur JSON pour le champ d’en-tête X-Mailgun-Variable. Cela démontre la puissance des webhooks : nous pouvons glisser des informations importantes ou des valeurs uniques dans ce champ d’en-tête et les récupérer lorsque Mailgun envoie le webhook à notre serveur.

Dans cet exemple précis, l’envoi de l’email est déclenché par un simple bouton HTML côté client. Nous avons encapsulé la fonctionnalité d’envoi d’email dans une méthode Meteor afin qu’elle soit accessible depuis le client. Voir le code d’envoi d’email ici.

N’oubliez pas de conserver les éléments importants tels que les identifiants API dans le dossier serveur de votre application Meteor. Les fichiers du dossier serveur ne sont pas envoyés au client. En revanche, les autres fichiers, qu’ils se trouvent dans le dossier client ou à la racine du dossier de l’application, peuvent se retrouver dans le navigateur du client.

Lorsque Mailgun détectera que notre email a été ouvert, il nous enverra une requête POST. Comme pour tout invité, nous voulons que le webhook soit bien accueilli et sache qu’il est arrivé à la bonne destination : pas d’erreurs 404 ici ! Le routage côté serveur n’est pas encore intégré à Meteor, mais ne vous inquiétez pas, grâce à la flexibilité de la plateforme, nous pouvons ajouter une route simple pour le webhook Mailgun sans avoir à tout démonter. La configuration d’une route côté serveur implique un peu plus de code :

                                

                                    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);

                                
                            

Vers le milieu, vous verrez où nous effectuons un calcul HMAC rapide pour confirmer l’identité de l’expéditeur. Mailgun fournit un jeton de signature avec chaque webhook et nous pouvons vérifier la validité de cette signature en hachant le jeton et l’horodatage fournis avec notre clé API. Ce n’est pas une exigence, mais c’est recommandé pour toute application publique. C’est très simple à réaliser en utilisant la méthode HMAC présente dans la bibliothèque crypto.

Avec cette route en place et activée sur notre serveur, nous pouvons préparer le côté Mailgun pour nos webhooks.

Si vous vous connectez à Mailgun, vous verrez l’onglet de suivi en haut de votre tableau de bord. En bas de la page de suivi, vous verrez un champ pour saisir la destination des requêtes POST que Mailgun enverra à chaque ouverture d’email.

Dans cette application de démo, nous attribuons à chaque session de navigateur un identifiant unique que nous incluons dans l’appel à l’API de Mailgun (dans cet en-tête HTTP X-Mailgun-Variables que nous avons envoyé plus tôt). Lorsque le webhook d’ouverture revient, nous pouvons inspecter non seulement les détails de géolocalisation, mais également analyser ce code d’identifiant de session unique. C’est ainsi que nous saurons à quelle session de navigateur appartient le webhook et que nous pourrons afficher le bon emplacement sur la carte.

Grâce à la puissance du framework Meteor, le navigateur (le client) peut observer toute modification dans l’ensemble de données des webhooks reçus. En utilisant l’événement de collection added côté client, le client est mis à jour immédiatement lorsque nous avons ajouté un nouvel événement webhook à notre base de données. Dans l’événement added, il nous suffit de générer un marqueur de localisation Google Maps en utilisant les valeurs de la ville, de la région et du pays figurant dans le webhook. C’est également ici que nous allons vérifier l’identifiant unique par rapport à notre identifiant de session actuel ; s’ils correspondent, ce marqueur est placé au premier plan sur la carte (avec un z-index) et signalé par une icône rouge.

La dernière partie du code côté client consiste à s’assurer que chaque marqueur sur la carte comporte une fenêtre pop-up contenant quelques autres détails sur le navigateur que Mailgun inclut également dans les données du webhook. Les webhooks de suivi de Mailgun incluent également des données très utiles, telles que le système d’exploitation, le client de messagerie utilisé pour ouvrir ou lire le message et le type d’appareil (idéal pour analyser l’utilisation mobile par rapport à l’utilisation sur ordinateur !).

Et voilà : votre application Meteor est maintenant prête à recevoir les webhooks de suivi et d’ouverture de Mailgun, de manière fiable et sécurisée.

Pour voir tout cela en action, visitez le site de démonstration et le code source sur GitHub.

Auteur·trice: 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!