Aug 30, 2019
Deploying Signals for On-Premises: PowerMTA Integration
Entrons dans les détails de la configuration de PowerMTA pour Signaux SparkPost. Vous aurez besoin de
Un hôte sur lequel exécuter la dernière version de PowerMTA - soit une nouvelle machine, soit une machine existante
A SparkPost account with API key permission for “Incoming Events: Write” comme décrit ici
Nous allons configurer PowerMTA pour diffuser des événements sur votre compte SparkPost, puis vous pourrez utiliser ce qui suit :
Firstly, install (or upgrade) to PowerMTA 5.0 r4 or later, following the instructions d'installation habituelles de la v5.0 which are pretty straightforward. Then we’ll work through the following steps:
Configurer le connecteur PowerMTA to SparkPost Signals
Configurer le suivi de l'engagement avec un domaine de suivi personnalisé
Sélectionnez les flux de trafic PowerMTA à signaler aux signaux.
Vérifier que vos événements atteignent les signaux
Revoyez comment utiliser des noms significatifs qui apparaissent bien dans les rapports.
Nous couvrirons également les autres aspects spécifiques de la configuration de PowerPMTA utilisés dans notre démo de Signals :
événements FBL (plaintes pour spam) et rebonds à distance (hors bande)
Configuration de l'injection, y compris DKIM
Configuration FBL et OOB
Configuration et dénomination de VirtualMTA (et comment cela apparaît dans vos rapports SparkPost Signals)
Finally, there’s a “bonus feature” with code to ensure your campaign names are compatible with PowerMTA X-Job name conventions.
Configure PowerMTA connector
Le Signals configuration is described in the 5.0 Guide de l'utilisateur section 10.1. Here we’ll start with “Use Case #2”, which enables Signals for all traffic from this PowerMTA host, and enable SparkPost engagement tracking.
# # SparkPost Signals # <signals> clé api ##my ingest API key here## upload-url https://api.sparkpost.com/api/v1/ingest/events log-verbose true mini-espace libre 1G engagement-tracking sparkpost # this turns on the open and click tracking in PowerMTA customer-id 123 # Your SparkPost account number here </signals> enable-signals true
Voici ce que fait chaque attribut :
clé api
C'est unique à votre compte SparkPost, c'est la valeur que vous avez obtenue de SparkPost précédemment.
upload-url
Cette adresse doit correspondre à l'adresse de votre service API SparkPost, qu'elle soit américaine ou européenne. Pour plus d'informations, voir ici. Les valeurs habituelles sont :
SparkPost (US) : https://api.sparkpost.com/api/v1/ingest/events
SparkPost EU: https://api.eu.sparkpost.com/api/v1/ingest/events
log-verbose
Cette directive est optionnelle et lorsqu'elle est activée, elle donne un peu plus d'informations dans le fichier pmta.log, ce qui peut être utile pendant l'installation pour confirmer que tout fonctionne correctement. Chaque minute, même s'il n'y a pas de trafic, vous verrez :
2019-07-26 11:47:57 Signaux : Découvert 0 fichiers
Avec le trafic, vous verrez quelque chose comme :
2019-07-26 11:50:57 Signaux : A découvert sp1-0000000000003FBD.json 2019-07-26 11:50:57 Signaux : A transféré sp1-0000000000003FBD.json avec succès. 2019-07-26 11:50:57 Signaux : A découvert 1 fichier, a transféré 1 fichier avec succès
mini-espace libre
Cela indique à PowerMTA le seuil d'espace disque à partir duquel il doit commencer à supprimer les fichiers d'événements JSON SparkPost les plus anciens pour faire de la place aux nouveaux fichiers lorsque l'espace disque est faible.
enable-signals
This tells PowerMTA to upload to Signals, in this case globally for all traffic (more info ici, pour la v5.0). You can be more selective about what traffic streams to upload if you wish.
You can also mark particular PowerMTA traffic to be reported as belonging to a SparkPost subaccount – this is another way to distinguish one particular traffic stream from another.
suivi de l'engagement, identifiant client
PowerMTA’s Engagement Tracking solution defaults à la tracking domain for the SparkPost US-hosted service. You specify your SparkPost numeric customer ID; here’s les instructions pour le trouver.
Domaine de suivi
Pour les comptes SparkPost EU, ajoutez la ligne suivante :
tracking-domain pmta.eu.spgo.io # il s'agit du point de terminaison pour SparkPost EU
Domaine de suivi personnalisé
Si vous préférez utiliser votre propre domaine de suivi (ce qui est mieux du point de vue de la délivrabilité), procédez comme suit :
Create tracking domain with your DNS provider by creating a CNAME record. This will usually be a subdomain of your top-level domain, e.g. track.mycompany.com .
track.mycompany.com CNAME pmta.spgo.io # si vous avez un compte SparkPost US track.mycompany.com CNAME pmta.eu.spgo.io # si vous avez un compte SparkPost EU
You can also use HTTPS tracking domains, although this is more involved (see SparkPost configuration steps here).
Register tracking domain in your SparkPost account, and vérifiez-le. Wait a few minutes before trying this, to allow your DNS changes to propagate through the Internet, depending on your DNS provider.
Configurez PowerMTA pour qu'il utilise ce domaine au lieu du domaine par défaut, avec
tracking-domain yourdomain.com # Mettez votre propre domaine ici
Vous pouvez vérifier que les "pixels d'ouverture" ont été ajoutés et que les liens sont enveloppés, en examinant les données internes du courrier (dans Gmail, utilisez le menu en haut à droite et choisissez "Afficher l'original").
You’ll notice the open pixels au beginning and end of the HTML in the email. Each HTML link is also changed to have REF pointing à la tracking domain.
C'est tout ce dont vous avez besoin pour que les signaux SparkPost fonctionnent avec le suivi de l'engagement intégré à PowerMTA.
Empêcher le suivi de liens spécifiques dans votre courriel html
You can prevent PowerMTA from tracking specific links, by setting the custom attribute data-msys-clicktrack to “0” :
<a href="#" data-msys-clicktrack="0">Example</a>
PowerMTA n'enveloppera pas le lien. Il supprimera également cet attribut avant de transmettre le message à votre destinataire.
Sélectionnez les flux de trafic PowerMTA à signaler aux signaux.
Vous pouvez sélectionner les signaux à activer :
Globalement (c'est ce que nous avons utilisé dans l'exemple ci-dessus)
Pour certains MTA virtuels et pas d'autres
Pour certains pools MTA virtuels et pas d'autres
Pour des adresses "Sender" ou "From" spécifiques relayées par PowerMTA, en combinaison avec les sélections MTA virtuel / pool MTA virtuel
This configuration is very powerful and is illustrated through a series of exemples de cas d'utilisation (v5.0) in the User Guide.
Vérifier que vos événements atteignent les signaux
Voici une vue de SparkPost Signals, connectée à PowerMTA. Vous pouvez voir que le score de santé varie.
Les noms de campagne sont disponibles en tant que facettes de rapport, ainsi que le sous-compte, le pool IP, le fournisseur de boîtes aux lettres et le domaine d'envoi.
En plus de regarder les journaux PowerMTA , vous pouvez vérifier que les données d'événements atteignent SparkPost en regardant l'écran d'intégration des signaux.
In your SparkPost Recherche d'événements screen, you should see events appear within a few minutes. These will include Injection and Delivery events, as well as Bounce, and potentially Out-of-Band Bounce and Spam Complaint events, if you’ve already configured PowerMTA to handle those for you.
If you have Engagement Tracking enabled, you will also see open , initial_open , and click events.
Utiliser des noms significatifs qui apparaissent bien dans les rapports
Setting up the PowerMTA VirtualMTA Pool names and Job names to be meaningful and human-readable is well worth doing. These show up directly in your SparkPost Signals facets and the Rapport de synthèse.
Comme mentionné précédemment, vous n'avez pas besoin de créer ces pools dans votre compte SparkPost. SparkPost les récupère de votre configuration PowerMTA .
Voici comment les termes de configuration de PowerMTA se traduisent en termes de SparkPost.
PowerMTA termeSparkPost Rapports / Signaux termeRecipient Domain
(domain portion of “rcpt” field in Accounting file).Recipient DomainLe domain portion of the “Sender” or “From” header in the message relayed by PowerMTA.
(domain portion of “orig” in Accounting file).Sending DomainVirtualMTA (name)—VirtualMTA Pool (name)
(“vmtaPool” in accounting file)IP Pool (name)smtp-source-host a.b.c.d
(“dlvSourceIp” in accounting file)Sending IP a.b.c.dJob (name)
(“jobId” in accounting file)Campaign ID (name)—Template (name)“Subaccount” is not a native PowerMTA concept.
Cependant, PowerMTA peut marquer les MTA virtuels, les pools MTA virtuels ou les domaines Sender-or-From avec un ID de sous-compte à des fins de reporting SparkPost.
ID du sous-compte (numéro)FBL (événement)Plainte pour spam (événement)Rebond à distance (événement)Rebond hors bande (événement)
Setting up at least one smtp-source-host address also enables SparkPost to correctly identify the sending IP address so that it shows up on Injection and Delivery events, as well as in the Rapport de synthèse view.
Job names are set in PowerMTA via a header in the injected message. As well as enabling individual job control (pause/resume etc) which is useful in itself, PowerMTA passes the names through to SparkPost Signals reporting as “campaign ID”. See User Guide v5.0 section 12.8 "Suivre une campagne sur PowerMTA avec un JobID".
There are a few things to be aware of regarding job naming. While SparkPost (with JSON format, and JSON escaping) allows characters such as <SPACE> in campaign names, mail headers are more restrictive. Valid characters allowed in the X-Job header are:
A-Za-z0-9!#$%&'()*+,-./:;<=>?@[\]^_{|}~
In other words, disallowed characters include <SPACE>, double-quotes “ and backtick `. If you’re used to working with X-Job names, this won’t be surprising, and your campaign ID names will “just work” on SparkPost reporting. If like me, you learned SparkPost first, you might want a tool to ensure your X-Job values are safe; see the bonus feature au end of cet article.
événements FBL (plaintes pour spam) et rebonds à distance (hors bande)
PowerMTA peut recevoir et traiter des événements FBL (connus dans SparkPost sous le nom d'événements Spam Complaint) et des rebonds à distance (connus dans SparkPost sous le nom de rebonds hors bande, parce que la réponse est renvoyée quelque temps après, plutôt que pendant la conversation SMTP).
There are articles in the Port25 Soutien Forum on how to set up the Processeur de rebonds and the Processeur FBL. If you are an existing PowerMTA user, you probably already have these.
Voici la configuration que j'ai faite pour une démo, basée sur ces articles et orientée vers l'hébergement de PowerMTA dans Amazon EC2.
Si vous connaissez la configuration de PowerMTA dans cette zone, vous pouvez sauter cette partie, jusqu'à la ligne horizontale suivante.
Configuration de l'injection
Nous utiliserons le port 587 pour les messages injectés, qui arriveront sur l'Internet public depuis un autre hôte. Nous devons empêcher les mauvais acteurs de découvrir et d'abuser de ce service, nous appliquons donc l'authentification par nom d'utilisateur/mot de passe et TLS facultatif, comme pour les points d'extrémité d'injection SMTP de SparkPost.
Nous voulons être en mesure d'envoyer des messages à partir de sources correctement authentifiées vers n'importe quelle destination. Nous voulons également un auditeur séparé sur le port 25 pour les réponses FBL et les réponses de rebond à distance qui ne nécessitent pas d'authentification.
# # Adresse(s) IP et port(s) sur lesquels écouter les connexions SMTP entrantes # smtp-listener 0.0.0.0:587 smtp-listener 0.0.0.0:25
In the following <source> declarations, we’re using username/password authentication and optional TLS to defend against rogue message injection. We also set rate limits on connections making failed password attempts.
Votre configuration peut être différente ; par exemple, si vous disposez d'un réseau privé entre l'injecteur et PowerMTA, vous n'aurez pas besoin d'une authentification par mot de passe.
# One source rule for all injection, internal or external. Enforce auth, except for bounces and FBLs # <source 0/0> log-connections false log-commands false # WARNING: verbose! just for dev log-data false # WARNING: even more verbose! smtp-service true # allow SMTP service smtp-max-auth-failure-rate 1/min allow-unencrypted-plain-auth false allow-starttls true rewrite-list mfrom </source> <source {auth}> always-allow-relaying yes # only if the auth succeeds default-virtual-mta default process-x-job true </source>
The <source {auth}> declaration (voir ici. v5.0) applies once authentication has passed. Here, it allows onward relaying, sets up the default virtual MTA group to use, and adds the X-Job header (which will be reported by SparkPost Signals as campaign_id).
La liste de réécriture fait en sorte que les messages injectés utilisent un domaine MAIL FROM spécifique (aussi appelé domaine de rebond ou Return-Path :).
# # Rewrite the MAIL FROM address to match the bounce domain # <rewrite-list mfrom> mail-from *@pmta.signalsdemo.trymsys.net *@bounces.pmta.signalsdemo.trymsys.net </rewrite-list>
Then we set up our Configuration de TLS and SMTP username / password, according to recommandations actuelles.
# # Secure the inbound service with username, password and TLS. SMT 2020-06-15 # smtp-server-tls-certificate /etc/pmta/pmtasignalsdemo.pem smtp-server-tls-allow-tlsv1 false smtp-server-tls-allow-tlsv1.1 false smtp-server-tls-allow-tlsv1.2 true smtp-server-tls-allow-tlsv1.3 true # # SMTP users (authenticated via SMTP AUTH) # <smtp-user SMTP_Injection> password ##PUT YOUR PASSWORD HERE## authentication-method password </smtp-user>
We can check that the (insecure, déprécié) TLS v1.0 is not accepted using my favorite SMTP test tool, swaks.
swaks --server pmta.signalsdemo.trymsys.net --port 587 --to test@trymsys.net --from any@sparkpost.com --tls --tls-protocol tlsv1
Nous voyons :
*** Le démarrage de TLS a échoué (connect() : error:00000000:lib(0):func(0):reason(0)) *** STARTTLS tenté mais échoué
Likewise for -tls-protocol tlsv1_1.
Let’s also apply DKIM signing on our outgoing messages, as it’s good practice (I followed ces instructions to set up the key).
# # DKIM # domain-key mypmta, pmta.signalsdemo.trymsys.net, /etc/pmta/mypmta.pmta.signalsdemo.trymsys.net.pem
Configuration FBL et OOB
Now .. finally .. we declare which specific domains are open for remote bounce and FBL responses. We don’t want to relay those anywhere (to prevent attaques par rétrodiffusion), just internally process those responses.
# # Enable Bounce and FBL processing on specific domains # relay-domain pmta.signalsdemo.trymsys.net relay-domain bounces.pmta.signalsdemo.trymsys.net relay-domain fbl.pmta.signalsdemo.trymsys.net <bounce-processor> deliver-unmatched-email no deliver-matched-email no <address-list> domain pmta.signalsdemo.trymsys.net domain bounces.pmta.signalsdemo.trymsys.net </address-list> </bounce-processor> <feedback-loop-processor> deliver-unmatched-email no deliver-matched-email no <address-list> domain fbl.pmta.signalsdemo.trymsys.net </address-list> </feedback-loop-processor>
You can see I set up two bounce domains, as I was playing around with using/not using the mfrom rewrite rule.
The FBL domain is usually then registered with external services such as Microsoft SNDS; see this article for more information. For this demo, the FBLs will be coming from the Évier à rebondissement, so no need to register.
Test de l'écouteur SMTP
Il est important de vérifier que votre récepteur SMTP exige une autorisation pour toutes les destinations générales et rejette tous les messages qui ne sont pas spécifiquement adressés aux domaines FBL et remote-bounce.
swaks --server pmta.signalsdemo.trymsys.net --port 25 --to test@strange.pmta.signalsdemo.trymsys.net --from any@sparkpost.com
La réponse, comme prévu, montre que le relais est refusé :
550 5.7.1 relaying denied for recipient in "RCPT TO:<test@strange.pmta.signalsdemo.trymsys.net>
(Fin de la description de la configuration de la démo).
Configuration et dénomination de VirtualMTA
PowerMTA Les VirtualMTAs (et les pools de VirtualMTAs) sont des fonctions puissantes pour gérer les flux de messages, et les fonctions de reporting PowerMTA / SparkPost Signals fonctionnent mieux avec ces fonctions actives.
# # Route all outgoing traffic through this virtual mta / pool. # Declare the delivery IP address here, so that SparkPost signals ingest injection (aka "reception") events # will carry the correct sending_IP attribute # <virtual-mta mta1> smtp-source-host 172.31.25.101 pmta.signalsdemo.trymsys.net </virtual-mta> <virtual-mta-pool default> virtual-mta mta1 <domain *> max-smtp-out 20 # max. connections *per domain* bounce-after 4d12h # 4 days, 12 hours retry-after 10m # 10 minutes dkim-sign yes </domain> </virtual-mta-pool>
The virtual-mta-pool setting is reported in SparkPost as “IP Pool”, and is available as a SparkPost Signals reporting facet (the drop-down menu underneath the charts).
Le rapport de synthèse présente également le pool d'adresses IP comme une facette de rapport "Group By".
As noted earlier in this article, setting up at least one smtp-source-host address also enables SparkPost to correctly identify the sending IP address, so that it shows up on Injection and Delivery events, and on the Summary Report:
That’s all you need to get a basic integration working between PowerMTA and SparkPost Signals. You’ll find the exemple complet de fichier de configuration ici.
Avant de partir, voici le bonus dont j'ai parlé.
Fonction bonus : Vérification/filtrage des noms d'emplois X
To ensure any character string is safe for use as a PowerMTA X-Job name, here’s a simple Python function to map any unsafe characters to an underscore “_”
import re def pmtaSafeJobID(s): """ :param s: str :return: str Map an arbitrary campaign ID string into allowed chars for PMTA X-Job header. See https://download.port25.com/files/UsersGuide-5.0.html#tracking-a-campaign-in-powermta-with-a-jobid Specifically disallow <sp> " ` but allow through most other chars. """ # Note have to escape ' - [ ] and double-escape \ - see https://docs.python.org/3/library/re.html disallowedChars = '[^A-Za-z0-9!#$%&\'()*+,\-./:;<=>?@\[\\\\\]^_{|}~]' return re.sub(disallowedChars, '_', s)
This uses Expressions régulières Python in a specific way. It declares the set of disallowed characters using the “set complement” operator ^ rather than list all allowed chars. That means we catch (and make safe) characters beyond the usual 7-bit set. We can show that using this test fragment:
s='' for i in range(32, 256) : s += chr(i) print(pmtaSafeJobID(s))
Donner
_!_#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^__abcdefghijkl mnopqrstuvwxyz{|}~___________________________________________________________ ______________________________________________________________________
You can see that <SPACE>, double-quotes “, and backtick `, as well as all characters beyond ~ are mapped to underscore.