Demo: Meteor-basierter E-Mail-Dienst mit Geolocation und UA-Tracking

Im Januar gaben wir unsere Partnerschaft mit Meteor bekannt, um das E-Mail-Back-End bereitzustellen, das in die Meteor-Plattform integriert ist. Werfen Sie als Beispiel einen Blick auf dieses Formular zur Event-Registrierung an, über das wir kürzlich berichtet haben. Heute möchten wir jedoch ein weiteres Beispiel für die Mailgun-Integration mit Meteor demonstrieren.

Vor ein paar Wochen haben wir neue Parameter für unsere Webhooks eingeführt, um Geolocation- und User-Agent-Informationen für Ihre E-Mails abzurufen, ohne UA-Strings parsen oder IP-Lookup-Bibliotheken nutzen zu müssen. Wir dachten, es wäre spannend, eine kleine App auf Basis von Meteor zu entwickeln, um zu demonstrieren, wie einfach es ist, diese neuen Parameter zu nutzen.

Klicken Sie auf die untenstehende Demo, um sie in Aktion zu sehen, und laden Sie den Quellcode der App von GitHub herunter, damit Sie damit experimentieren und Ihre eigene App oder Ihren eigenen Bericht erstellen können. Wenn Sie die Demo getestet haben, kehren Sie hierher zurück. Wir gehen dann genauer darauf ein, wie wir sie entwickelt haben.

Versenden Sie E-Mails mit Mailgun ganz einfach über Standard-SMTP oder die Mailgun-HTTP-API. Wenn Sie lediglich eine einfache SMTP-Versandfunktion in Ihrer Meteor-Anwendung benötigen, fügen Sie zunächst das E-Mail-Paket zu Ihrem Projekt hinzu.

>> meteor add email

Nach der Ausführung dieses Befehls wird automatisch ein Standard-Mailgun-Konto konfiguriert. Zudem legt Meteor automatisch die Umgebungsvariable MAIL_URL fest, die die SMTP-Konfiguration speichert. (Weitere Informationen finden Sie in der E-Mail-Dokumentation auf der Meteor-Website. hier. Wie im letzten Absatz erwähnt, lässt sich der Versand auch ohne das E-Mail-Paket testen: Standardmäßig werden E-Mails direkt in der Konsole ausgegeben).

Für diese Demo gehen wir über den grundlegenden E-Mail-Versand hinaus. Deshalb nutzen wir direkt ein Mailgun-Konto sowie die HTTP-API (übrigens: Bei der Nutzung der API setzt Mailgun den MIME serverseitig zusammen, was die Handhabung selbst bei einfachem E-Mail-Versand etwas erleichtert).

Kopieren Sie zunächst Ihren API-Schlüssel aus dem Mailgun-Control-Panel. Dieser wird Ihnen nach der Anmeldung angezeigt.

Die API wird mit einer einfachen HTTP-POST-Anfrage aufgerufen. Fügen Sie dazu das http-Paket von Meteor zu Ihrem Projekt hinzu.

>> meteor add http

Nach der Installation des http-Pakets führen Sie in Ihrer Anwendung beliebige HTTP-Anfragen (GET, POST, PUT, DELETE usw.) aus.

Kommen wir zu den wesentlichen Details: Im Folgenden sehen Sie ein Beispiel dafür, wie eine E-Mail mit Mailgun über die API versendet wird:

                                

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

Gehen wir hier auf einige Details ein.

Wie Sie sehen, legen wir für diese Anfrage mithilfe einer Umgebungsvariablen namens MAILGUN_API_KEY eine Authentifizierungs-Kopfzeile fest. Auf der Meteor-Hosting-Plattform (z. B. meteor deploy) lassen sich noch keine Umgebungsvariablen festlegen. Wenn Sie Ihre Meteor-App jedoch auf Heroku oder einem eigenen Setup ausführen, ist es sinnvoll, Zugangsdaten wie Ihren API-Schlüssel sicher in einer Umgebungsvariablen aufzubewahren. Um eine Umgebungsvariable mit Meteor festzulegen, gehen Sie wie folgt vor:

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

Beachten Sie auch, dass wir hier einige benutzerdefinierte Tracking-Werte hinzufügen.

• Die Tracking-Option wird auf „true“ gesetzt, um Mailgun mitzuteilen, dass der Webhook beim Öffnen der E-Mail ausgelöst werden soll.
• Ein JSON-Wert wird für das Feld X-Mailgun-Variable in der Kopfzeile festgelegt. Dies zeigt das Potenzial von Webhooks: Wir hinterlegen wichtige Details oder eindeutige Werte in diesem Kopfzeilen-Feld und rufen sie wieder ab, wenn Mailgun den Webhook an unseren Server sendet.

In diesem speziellen Beispiel wird der E-Mail-Versand durch einen einfachen HTML-Button auf der Client-Seite ausgelöst. Wir haben die E-Mail-Versandfunktion in eine Meteor-Methode eingebunden, damit sie vom Client aus zugänglich ist. Hier finden Sie den Code für den E-Mail-Versand.

Denken Sie daran, wichtige Informationen wie API-Zugangsdaten im Server-Ordner Ihrer Meteor-Anwendung aufzubewahren. Dateien im Server-Ordner werden nicht an den Client gesendet. Andere Dateien, die sich entweder im Client-Ordner oder im Stammverzeichnis des Anwendungsordners befinden, können hingegen in den Browser des Clients gelangen.

Sobald Mailgun erkennt, dass unsere E-Mail geöffnet wurde, sendet es eine POST-Anfrage an uns. Wie bei jedem Gast möchten wir, dass sich der Webhook willkommen fühlt und weiß, dass er am richtigen Zielort angekommen ist: 404-Fehler sind hier unerwünscht. Serverseitiges Routing ist in Meteor noch nicht integriert. Aber keine Sorge: Dank der Flexibilität der Plattform fügen wir mühelos eine einfache Route für den Mailgun-Webhook hinzu, ohne alles zerlegen zu müssen. Bei der Einrichtung einer serverseitigen Route ist etwas mehr Code erforderlich:

                                

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

                                
                            

Etwa in der Mitte sehen Sie, wo wir eine schnelle HMAC-Berechnung durchführen, um die Identität des Absenders zu bestätigen. Mailgun stellt mit jedem Webhook ein Signatur-Token bereit. Wir überprüfen die Gültigkeit dieser Signatur, indem wir das bereitgestellte Token und den Zeitstempel mit unserem API-Schlüssel hashen. Dies ist keine zwingende Anforderung, für öffentlich zugängliche Anwendungen jedoch durchaus sinnvoll. Mithilfe der HMAC-Methode in der Krypto-Bibliothek lässt sich dies unkompliziert umsetzen.

Sobald diese Route auf unserem Server eingerichtet und aktiviert ist, bereiten wir bei Mailgun alles für unsere Webhooks vor.

Nach der Anmeldung bei Mailgun sehen Sie oben in Ihrem Dashboard den Tab für das Tracking. Unten auf der Tracking-Seite finden Sie ein Feld zur Eingabe des Ziels für die POST-Anfragen. Mailgun sendet diese bei jedem Öffnen einer E-Mail.

In dieser Demo-Anwendung weisen wir jeder Browser-Sitzung eine eindeutige ID zu, die wir in den Aufruf der Mailgun-API integrieren (in die HTTP-Kopfzeile X-Mailgun-Variables, die wir zuvor gesendet haben). Wenn der Open-Webhook zurückgegeben wird, überprüfen wir nicht nur die Geolocation-Details, sondern parsen auch den Code dieser eindeutigen Sitzungs-ID. Auf diese Weise ordnen wir den Webhook der richtigen Browser-Sitzung zu und zeigen den korrekten Standort auf der Karte an.

Dank der Leistungsfähigkeit des Meteor-Frameworks beobachtet der Browser (der Client) alle Änderungen am Datensatz der empfangenen Webhooks. Mithilfe des Ereignisses „added“ für die Collection auf dem Client wird dieser sofort aktualisiert, sobald wir unserer Datenbank ein weiteres Webhook-Ereignis hinzufügen. Innerhalb des Ereignisses „added“ erstellen wir lediglich einen Standort-Marker für Google Maps. Dabei greifen wir auf die Werte für Stadt, Region und Land im Webhook zurück. An dieser Stelle vergleichen wir zudem die eindeutige ID mit unserer aktuellen Sitzungs-ID. Stimmen sie überein, wird dieser Marker mit einem roten Symbol im Vordergrund der Karte (per z-index) platziert.

Der letzte Teil des clientseitigen Codes stellt sicher, dass jeder Marker auf der Karte über ein Pop-up verfügt. Dieses enthält einige weitere Browser-Details, die Mailgun ebenfalls in die Webhook-Daten integriert. Die Tracking-Webhooks von Mailgun umfassen auch nützliche Daten wie das Betriebssystem, den zum Öffnen/Lesen der Nachricht verwendeten E-Mail-Client sowie den Gerätetyp (ideal zur Analyse der mobilen im Vergleich zur Desktop-Nutzung).

Das war’s: Ihre Meteor-Anwendung ist nun bereit, Tracking- und Open-Webhooks sicher und zuverlässig von Mailgun zu empfangen.

Um das Ganze in Aktion zu sehen, besuchen Sie die Demo-Seite und den Quellcode auf 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!