Dokumentation: SMTP-Schnittstelle

Einführung

Dieses Dokument beschreibt die Verwendung der SMTP-Schnittstelle des EMM. Bitte beachten Sie, dass <Domain> ("example.com") in diesem Dokument ein Platzhalter für eine vom Anwender verwendete Domain ist, die in Verbindung mit dieser Anwendung genutzt wird.

Bitte verwenden Sie in einem realen Szenario nicht "example.com"! Verwenden Sie immer genau eine Domain als Schlüsseldomain für einen Konfigurationseintrag, verwenden Sie keine Domains für mehr als einen Konfigurationseintrag, auch nicht über mehrere EMM-Mandanten hinweg!

Die Konfiguration wird direkt in der „Beschreibung“ eines Mailings in der EMM-GUI eingerichtet.

Ein ergänzendes Glossar für verschiedene in dieser Dokumentation verwendeten Begriffe finden Sie unter Abschnitt Glossar.

Mailings erstellen

Jedes Mailing, das über die SMTP-Schnittstelle versendet werden soll, muss als "aktionsbasiertes Mailing" erstellt werden. Es wird nur verwendet, wenn es im EMM explizit aktiviert wird. Dies ermöglicht es, das Mailing für eine Inhaltsveränderung zu deaktivieren, ohne dass es während der laufenden Bearbeitung versendet wird.

Um ein Mailing für die Verwendung durch die SMTP-Schnittstelle zu markieren, muss die Namensgebung einem festen Muster folgen. Standardmäßig erwartet das Muster einen Namen in eckigen Klammern, dem optional ein beliebiger freier Text folgt, z.B.:

[invoice@<domain>]: Das ist die Schablone für Rechnungen

Um dieses Mailing auszuwählen, muss die Envelope-From E-Mail-Adresse des eingehenden Mailings wie folgt lauten:

invoice@<domain>

Für das aktuelle Beispiel:

invoice@example.com

So kann der EMM-Anwender verschiedene Vorlagen für verschiedene Zwecke hinzufügen, ohne dass AGNITAS für weitere Konfigurationen hinzugezogen werden muss.

Wenn Sie ein Mailing ohne den Domainteil erstellen, gilt dieses Mailing für alle Domains (nach dem @ in einer E-Mail-Adresse) dieses Konfigurationseintrags, die den Namen als Lokalteil (vor dem @ in einer E-Mail-Adresse) verwenden, z.B.:

[info]: Greift für alle Absenderadressen "info@<domain>" für alle bekannten Domains

Wenn Sie ein Mailing nur mit einem Stern (*) erstellen, wird dieses Mailing verwendet, wenn kein anderes Mailing für diese Absenderadresse gefunden wurde. Dies kann in Verbindung mit einer Domain verwendet werden wie beispielsweise

[*@example.com]: Greift für alle Absenderadressen, die "example.com" als  Domain verwenden

oder ohne eine Domain

[*]: Greift für alle Absenderadressen aller bekannten Domains für diesen Mandanten

Konfiguration

Der EMM-Nutzer hat die Möglichkeit das Versandverhalten weiter zu beeinflussen. Dafür können in der Beschreibung jedes Mailings weitere Konfigurationswerte hinzugefügt werden.

Wenn eine Zeile in der Beschreibung eine Konfiguration enthalten soll, muss diese Zeile mit der Zeichenfolge "pegi:" (bitte den abschließenden Doppeltpunkt nicht vergessen). Es können mehrere Einstellungen pro Zeile vorgenommen werden, diese müssen durch ein Komma getrennt werden.

Es gibt zwei verschiedene Konfigurationsparameter:

• token: diese schalten eine bestimmte Funktionalität ein und bedürfen keiner weiteren Informationen, z.B. keep-x-mailer
• setting: dies weist Konfigurationsparametern Werte zu, diese müssen durch ein Gleichheitszeichen angehängt werden, z.B. list-help=https://example.com/list-help.html

Beispiel:

pegi: keep-x-mailer, passthru-mfrom, list-help=https://example.com/list-help.html

ist gleichbedeutend mit

pegi: keep-x-mailer, passthru-mfrom
pegi: list-help=https://example.com/list-help.html

Folgende Konfigurationswerte werden derzeit unterstützt. Der Begriff in Klammern zeichnet aus, ob sie als token oder setting verwendet werden müssen:

keep-x-mailer (token)

Wenn diese Option verwendet wird, bleibt der von EMM generierte X-Mailer-Header erhalten.

list-help (setting)

Der gesetzte Wert wird für einen List-Help-Header verwendet, wenn die Mail keinen List-Unsubscribe-Header enthält und kein List-Help-Header in der ursprünglichen Mail enthalten war. Andernfalls wird der ursprüngliche List-Help-Header verwendet. Wenn dieser nicht gesetzt ist und ein Mailing-Parameter mit dem Namen "list-help" existiert, wird stattdessen dessen Wert verwendet.

passthru-mfrom (token)

Falls verwendet, wird der ursprüngliche Envelope der E-Mail-Adresse als ausgehende Envelope-From E-Mail-Adresse für die resultierende Mail verwendet.

passthru-from (token)

Falls verwendet, wird der From-Header aus dem ursprünglichen Header als From-Header für die ausgehende Mail verwendet. Außerdem wird, wenn ein Reply-To-Header in der ursprünglichen Mail enthalten ist, dieser Header auch in der ausgehenden Mail verwendet, andernfalls wird kein Reply-To-Header hinzugefügt.

passthru-to (token)

Falls verwendet, wird der To-Header aus der ursprünglichen Kopfzeile als To-Header für die ausgehende E-Mail verwendet.

link (setting)

Das Feature kann Links (URIs) aus dem Inhalt extrahieren und sie in messbare Redirect-Links umwandeln.

Je nach Quelle der eingehenden Mails müssen oder sollen nicht alle (oder sogar keine) URIs verfolgbar sein. Daher werden standardmäßig keine Links zum Nachverfolgen markiert, aber spezifische Links können mit diesem Einstellungsparameter ausgewählt werden. Diese Einstellung kann mehrfach hinzugefügt werden und wird vom EMM der Reihe nach abgearbeitet.

Die erste Übereinstimmung kontrolliert, ob ein Link messbar ist. Nach einer erfassten Übereinstimmung werden keine weiteren Regeln konsultiert. Wenn keine Regel zutrifft (oder keine Regeln verfügbar sind), wird ein Link nicht als messbar markiert (siehe unten für die Ausnahme, wenn nur Ausschlussregeln verwendet werden).

Jede Regel kann optional mit einem Kontrollblock beginnen, der in eckigen Klammern ("["..."]") eingeschlossen ist. Dieser Kontrollblock kann einzelne Zeichen enthalten, die die Anpassungslogik für diese Regel modifizieren. Zurzeit werden folgende Steuerelemente unterstützt

! (Ausrufezeichen):

Markiert eine Ausschlussregel, d.h. wenn die Regel selbst auf einen Link zutrifft, werden keine weiteren Regeln konsultiert und der Link wird als nicht messbar markiert.

i:

Aktiviert den Abgleich unter Berücksichtigung der Groß- und Kleinschreibung. Standardmäßig wird der Abgleich ohne Berücksichtigung der Groß- und Kleinschreibung verwendet.

Beispiel:

pegi: link = [i]https://*

Es gibt drei Arten von Regelmustern:

• Einfache Muster (Platzhalterstruktur)
• Muster für reguläre Ausdrücke
• Komplexe Muster

Dabei gilt: Wenn eine Regel von spitzen Klammern (< ... >) umgeben ist, handelt es sich um ein komplexes Muster. Wenn eine Regel von Schrägstrichen (/ ... /) umgeben ist, handelt es sich um Muster für reguläre Ausdrücke, ansonsten um ein einfaches Muster (Platzhalterstruktur). Beispiele zu allen Mustern folgen weiter unten.

Einfaches Muster (Platzhalterstruktur)

Dieses Muster unterstützt einfache Platzhalterzeichen:

• *: Passt auf eine beliebige Anzahl von Zeichen.
• ?: Entspricht genau einem Zeichen.
• [..]: Zeichenklasse, die genau einem Zeichen entspricht, wenn es Teil der Liste zwischen den eckigen Klammern ist.
• [!..]: Invertierte Zeichenklasse, die genau einem Zeichen entspricht, wenn es nicht in der Liste zwischen den eckigen Klammern enthalten ist.

Muster für reguläre Ausdrücke

Dieses Muster unterstützt erweiterte reguläre Ausdrücke anstelle eines einfachen Platzhalterausdrucks. Wenn zum Beispiel alle URIs als messbar markiert werden sollen, die mit "http://" oder "https://" beginnen, müssen Sie zwei Regeln mit dem folgenden einfachen Muster verwenden:

link = http://*, link = https://*

Bei der Verwendung von Mustern für reguläre Ausdrücke kann dies durch eine Regel angepasst werden:

link = /https?://.*/

Komplexe Muster

Diese Muster sind besonders nützlich, wenn man eine Regel auf einer Komponentenebene einer URI angeben möchte. Um zum Beispiel alle Links zu akzeptieren, die mit "http://" oder "https://" beginnen, kann dies wie folgt geschrieben werden:

link = <proto:http or proto:https>

Diese sind so etwas wie vereinfachte Suchmaschinenabfragen. Sie können den Musterabgleich auf einen Teil des URI beschränken, indem Sie dem Muster den entsprechenden Teil des URI voranstellen. Unterstützte Segmente sind:

• proto: das Protokoll (ähnlich zu “http”, “https”).
• host: der Domainname.
• path: der Pfad zur Entität.
• params: weitere Parameter.
• query: der Abfrageparameter.
• anchor: der Anker.

Wenn der Teil weggelassen oder auf * (Sternchen) gesetzt wird, wird das Muster mit dem gesamten URI abgeglichen.

Beispiel URI:

https://www.agnitas.de/search;fast?q=emm&l=en#result

Diese URI entspricht der Regel:

link = <proto:https and host:www.agnitas.de and path:/search and params:fast and query:q=emm&l=en and anchor:result>

Im obigen Beispielfall haben wir den Doppelpunkt als Trennzeichen verwendet. Es gibt noch ein paar weitere:

• :: Dies gleicht das Muster mit dem gewählten Teil ab und ermöglicht eine einfache Syntax für Platzhaltermuster.
• !: Dies kehrt das Ergebnis des einfachen Platzhalter-Mustervergleichs um.
• /: Dies gleicht das Muster mit dem gewählten Teil ab, der die Syntax eines regulären Ausdrucks erlaubt.
• !/: Kehrt das Ergebnis des Abgleichs mit dem regulären Ausdruck um.
• =: Prüft auf Gleichheit, hier wird kein Mustervergleich durchgeführt.
• !=, <>: Dies kehrt die Gleichheitsprüfung um.
• <, <=, =<, >, >=, =>: weniger, weniger oder gleich, größer, größer oder gleich, soweit dies bei einer textlichen Übereinstimmung sinnvoll ist.

Sie können Abfragen mit runden Klammern ("("..")") gruppieren, das Ergebnis mit "not" invertieren und die Abfragen mit "and" und "or" verketten. Eine fehlende Verkettung wird als "and" behandelt, so dass diese Beispiele die gleiche Bedeutung haben. Für mehr Übersichtlichkeit wird aber die Verwendung einer expliziten Verkettung empfohlen:

link = <proto:https host:www.agnitas.de>
link = <proto:https and host:www.agnitas.de>

Beispiele

Die folgenden Beispiele sind für alle drei Suchmuster-Varianten angelegt.

Beispiel 1: Markieren Sie alle Links als messbar (nicht empfohlen)

link = *
link = /.*/
link = <*>

Beispiel 2: Alle Links markieren, außer einem favicon.ico:

link = [!]*/favicon.ico
link = [!]/https?://[^/]+/favicon.ico$/
link = <path!:/favicon.ico>

Beispiel 3: Markieren Sie alle Links, die wichtig sind, als messbar, z. B. die Abfrage beginnt mit "/important/" (die Platzierung der Zeichenfolge in der URI ist hier nicht festgelegt, sie kann bei einfachen Mustern auch an anderer Stelle eingesetzt werden):

link = */important/*
link = /https?://[^/]+/important/.*/
link = <query:/important/*>

Beispiel 4: Alle Links markieren, die einen Anker haben “#track”:

link = *#track
link = /.*#track$/
link = <anchor:track>

Beispiel für Mailing-Einstellungen auf EMM-Oberfläche

Profilfeld Verwaltung

In jedem Mandanten, der für die SMTP-Schnittstelle freigeschaltet ist, werden eine Reihe von Profilfeldern automatisch angelegt. Diese können mit Hilfe von EMM agnTags (z.B. [agnDB column="..."/]) verwendet werden, um Inhalte aus der eingehenden E-Mail zu referenzieren. Die Inhalte aus der Datenbank werden dann in den ausgehenden E-Mails verwendet und eingefügt. Neben diesen Profilfeldern werden einige bereits vorhandene Standardfelder genutzt, um Informationen an das Zielmailing zu übergeben. Beispiel:

[agnDB column="content_subject"/]

Die Informationen zu diesen Profilfeldern werden in die Datenbank geschrieben und können später auch verwendet werden, um einen bestimmten Kunden zu referenzieren:

• email: Die E-Mail-Adresse des Empfängers, die als Envelope-to E-Mail-Adresse angegeben wurde.
• mailtype: Dies wird je nach eingehender Nachricht entweder auf 0 (für textformat) oder 1 (für HTML-Format) gesetzt. Fehlt in der Ursprungs-E-Mail ein HTML-Teil, so wird mailtype auf 0 gesetzt, andernfalls auf 1.
• firstname, lastname: Diese Werte werden aus dem Inhalt des Feldes "To" der eingehenden Kopfzeile extrahiert.
• mailing_id: Die ID des ausgehenden Mailings, das für die eingehende Absenderadresse ausgewählt wurde.
• message_id: Der Inhalt der Kopfzeile "Message-ID" der Originalmail, die vom User der SMTP-Schnittstelle eingeliefert wurde. Nachdem der Inhalt dieses Feldes vom Nutzer vorgegeben werden kann, kann dieses als primäres Kriterium zur Zuordnung der Originalmail zu der aus dem EMM verschickten Mail verwendet werden.

Der Inhalt der nachfolgenden Profilfelder wird nicht in der Datenbank gespeichert, sondern "on-the-fly" während des Sendevorgangs für die ausgehende Mail übergeben, d.h. diese Informationen können nicht nachträglich aus dem Profil des Empfängers abgerufen werden und stehen auch in einer Fullview nicht zur Verfügung:

• content_text: Der Textteil des Bodies der eingehenden Mail.
• content_html: Der HTML-Teil des Bodies der eingehenden Mail.
• content_subject: Der Inhalt des Feldes "Subject" der eingehenden Kopfzeile.
• content_sender: Die eingehende Envelope-From E-Mail-Adresse des Absenders.
• content_from: Der Feldinhalt des eingehenden Headers "From".
• content_from_name: Der visuelle Teil (echter Name) von content_from.
• content_from_email: Der E-Mail-Adressteil von content_from (falls nicht gefunden, wird der Feldinhalt von content_sender verwendet)).
• content_to: Der Feldinhalt des eingehenden Headers "To".
• content_to_name: Der visuelle Teil (echter Name) von content_to.
• content_to_email: Der E-Mail-Teil für content_to (falls nicht gefunden, wird der Feldinhalt von email verwendet)).
• content_reply_to: Der Feldinhalt des eingehenden Headers "Reply-To".
• content_header: Der gesamte eingehende Header in maschinenlesbarer Form als JSON.

Für jeden Anhang werden drei zusätzliche Profilfelder verwendet, jedes mit einer laufenden Nummer, um mehr als einen Anhang zu ermöglichen. Diese werden hier primär zu Informationszwecken bereitgestellt, da diese Informationen intern verarbeitet werden.

• att_1_filename: Der Dateiname des ersten Anhangs.
• att_1_mimetype: Der MIME-Typ (Dateityp) des ersten Anhangs.
• att_1_content: Der Anhang selbst, welcher bereits base64-kodiert ist.
• att_2_filename, att_2_mimetype, att_2_content: Für den zweiten Anhang.

Beispiel für Profilfelder auf EMM-Oberfläche

Beispiel für Mailing-Inhalte auf EMM-Oberfläche

Datenverwaltung

Es kann sinnvoll sein, in der eingehenden E-Mail zusätzliche Informationen einzufügen, die im Empfängerprofil im EMM gespeichert werden. Dies kann durch Hinzufügen von Kopfzeilen zur eingehenden E-Mail geschehen, die mit dem Buchstaben "X" beginnen,. Das "X" kennzeichnet sie dabei als benutzerdefinierte Kopfzeile.

Ergänzend muss ein entsprechendes Profilfeld mit demselben Namen in einer „normalisierten“ Variante vorhanden sein. Diese „normalisierte“ Variante muss mit dem Text "head_" beginnen, gefolgt von der Kleinbuchstabenform des Kopfzeilenfeldes, wobei der Bindestrich ("-") durch einen Unterstrich ("_") ersetzt wird. Beispiele zur Erfassung des Profilfeldwertes:

Kopfzeile: „X-Mailer“
Profilfeld: „head_x_mailer“

Kopfzeile: „X-EMM-Status“
Profilfeld: „head_x_emm_status“

Glossar

AgnTags

Die Abkürzung für AGNITAS-Tags. Diese sind Platzhalter für Inhalte aus der Datenbank, die bei der Generierung eines Mailings eingefügt werden.

Aktionsbasiertes Mailing

Aktionsbasierte Mailings oder auch „Aktionsgesteuertes Mailing“ werden standardmäßig erst durch eine oder mehrere spezifische Aktionen ausgelöst und verschickt. Was der Auslöser ist und welchen Inhalt Sie daraufhin verschicken, kann individuell durch Sie bestimmt werden. Es gilt hierbei grundsätzlich zu beachten, dass im EMM unter dem Menüpunkt „Mailings“ ein solches aktionsbasiertes Mailing sowie unter dem Menüpunkt „Trigger-Verwaltung“ ein auslösender Trigger, welcher in diesem Anwendungsfall der Aufruf per SMTP-Schnittstelle ist, angelegt werden müssen. Der Trigger muss hierbei mit dem Mailing verknüpft werden und das Mailing selbst unter „Versand“ auf aktiv geschaltet werden, damit ein Versand unter den gesetzten Rahmenbedingungen erfolgt.

Body

Eine E-Mail besteht aus dem Header-Abschnitt (englisch für: „Kopfzeile“) und dem Body (englisch für „Rumpf“) dem eigentlichen Inhalt der Nachricht.

Domain

Eine E-Mail-Domain ist der Teil einer E-Mail-Adresse, der nach dem „@“ kommt, zum Beispiel @agnitas.de. Dieser Teil der Adresse gibt an, wo sich die Adresse im Domain-Name-System (DNS) befindet, und wird auch als Domain Part bezeichnet.

Empfängerprofil

Zu jedem Empfänger befinden sich in der Datenbank des EMM spezifische Daten – sein sogenanntes Empfängerprofil. Sie rufen die Daten jedes Empfängers auf, indem Sie in der Übersicht der EMM GUI auf den entsprechenden Eintrag klicken. Im Inhaltsbereich erscheint auf der linken Seite im Register Empfänger ein Eingabedialog mit den Daten für den gewählten Empfänger.

Envelope-From/Envelope-To E-Mail-Adresse

Die Envelope-From und Envelope-To E-Mail-Adressen werden vom Mailserver beim Versand verwendet und dienen während des Versandprozesses als die primäre Information für die Zustellung. Während die Envelope-From Adresse hier herangezogen wird, um Statusrückmeldungen zu verschicken (z.B. Empfänger existiert nicht), wird die Envelope-To Adressen zur Ermittlung des eigentlichen Empfängers verwendet.

Die Envelope-From Adresse kann bei der finalen Zustellung in der Kopfzeile "Return-Path" eingetragen worden sein. Die Envelope-From und Envelope-To E-Mail-Adressen können, müssen aber nicht, identisch mit der E-Mail-Adresse in den Kopfzeilen "From" respektive "To" sein (also die Adressen, die der Empfänger im E-Mail-Header in seinem E-Mail-Programm sieht).

From-Header

Jede E-Mail enthält zwei Absenderadressen: „Envelope From“ und „Header From“. Die Adresse „Header From“ ist das, was umgangssprachlich als Absenderadresse verstanden wird. Sie ist für alle E-Mail-Benutzer sichtbar und wird im „From“-Feld einer E-Mail angezeigt. Diese Adresse wird von Benutzern und E-Mail-Clients gelesen, wird aber nicht für die E-Mail-Zustellung verwendet. Stattdessen dient sie der Identifikation des sichtbaren Absenders, beeinflusst die Darstellung in E-Mail-Programmen und ist relevant für Funktionen wie „Antworten“ (Reply), die Vertrauenswürdigkeit einer Nachricht sowie Authentifizierungsverfahren wie DMARC, bei denen geprüft wird, ob die sichtbare Absenderadresse mit den technischen Versandinformationen übereinstimmt.

List-Help-Header

Ein List-Help-Header ist ein mailto- oder https-Link, welcher zu einer Seite führt, die ein Abmeldeformular enthalten kann, Gründe aufzählt, warum der/die Empfänger:in die E-Mail erhalten hat, Anweisungen zur Abmeldung liefert oder Erklärungen bietet, warum eine Abmeldung nicht möglich oder notwendig ist (z.B. bei E-Mails zum Zurücksetzen des Passworts).

List-Unsubscribe-Header

Ein List-Unsubscribe-Header (auch als „Ein-Klick-Abmeldung“ bezeichnet) ist ein E-Mail-Header, der detaillierte Anweisungen über den Abmeldeprozess eines Versenders enthält. Verbreitete Mailbox Providerl wie Gmail oder Outlook nutzen diese Informationen, um in Postfächern einen zusätzlichen Link zum Abbestellen anzuzeigen.

Mailing / Mail

Mailing beschreibt verschiedene Formen der Einrichtung eines Mailversandprozesses, welche im Fall des EMMs normale, aktionsbasierte, intervallgesteuerte oder datumsgesteuerte Mailings sein können. Eine Mail ist eine einzelne Sendung an einen Empfänger/eine Empfängerin, welche durch das aufgesetzte Mailing versendet wurde.

Mailing ID

Eine individuell vergebene ID-Nummer, die der EMM in verschiedenen Anwendungen zur eindeutigen Identifikation von Mailings verwendet.

Messbare Links

Ein messbarer Link ist ein in einen für den EMM messbaren Redirect-Link umgewandelter Link, mit dem statistische Daten zu Linkklicks eines Mailversands erfasst werden können.

Profilfeld

Zu jedem Empfänger verwaltet der EMM in seiner Datenbank ein Profil. Das Empfängerprofil enthält standardmäßig Daten wie z.B. Anrede, Vorname, Nachname und natürlich die E-Mail-Adresse. Diese Daten werden über sogenannte Profilfelder strukturiert und gespeichert.

Reply-To-Header

Eine oder mehrere durch Kommas getrennte E-Mail-Adressen, an die eine Antwort auf die E-Mail geschickt werden soll (falls die Einträge unterschiedlich zum From-Feld sind).

To-Header

Eine oder mehrere durch Kommas getrennte E-Mail-Adressen, an die die E-Mail primär gesendet wird.

URI / URL

Ein Uniform Ressource Identifier (URI) ist nach Definition der RFC eine kompakte Abfolge von Zeichen, die eine abstrakte oder physische Ressource identifizieren. Das kann verallgemeinert z.B. eine Seite, ein Buch oder ein Dokument sein. Der Begriff Uniform Resource Locator (URL) bezieht sich auf eine Teilmenge der URIs. Diese geben neben der eigentlichen Identifizierung auch ein Mittel zur Lokalisierung der Ressource an. Im Rahmen dieses Dokuments sprechen wir explizit von URI.

X-Mailer-Header

Ein X-Mailer-Header ist ein Header mit dem Namen "X-Mailer" und fällt damit unter die Kategorie der "X-Header". Er ist kein standardisierter Header und hat in diesem Fall nur einen informellen Zweck.

Als "X-Header" werden allgemein Kopfzeilen bezeichnet, die nicht standardisiert sind und die durch die Notation mit vorangestelltem "X-" auch explizit von einer Standardisierung ausgeschlossen sind. Diese können damit informellen Charakter haben oder für interne Zwecke genutzt werden.