Mail API

Die Mail API macht aus Ihren E-Mails Nachrichten: Sie schicken eine Mail an die Adresse Ihrer Konfiguration, wir werten sie anhand Ihrer Muster aus und versenden das Ergebnis als SMS, RCS, WhatsApp oder Voice-Nachricht. Wo in der Mail der Empfänger, der Text und der Absender stehen, beschreiben Sie einmal in der Konfiguration. Empfänger können Rufnummern, Kontakte oder Gruppen aus Ihrem Adressbuch sein.

Feste Adresse mit Mail-Mustern

Jede Mail-API-Konfiguration hat eine feste, systemgenerierte Adresse und drei Muster. Die Muster beschreiben, wie Ihre Mails aussehen: wo der Empfänger steht, wo der Nachrichtentext steht und was sonst noch in der Mail vorkommt. So richtet sich die Mail API nach Ihrer Anwendung. Die Konfiguration selbst legen Sie wie im Abschnitt Einrichtung beschrieben an.

Aufbau der Adresse

Die Adresse besteht aus einem festen Token und einem optionalen Prefix davor:

TOKEN@gateway.seven.io
PREFIX.TOKEN@gateway.seven.io

TOKEN wird von uns erzeugt, ist fest und wird Ihnen in Ihrem Login unter Entwickler > API Zugänge angezeigt. PREFIX wählen Sie pro Mail frei: alles vor dem letzten Punkt des lokalen Teils ist der Prefix und wird über das Muster für den Adress-Prefix ausgewertet.

Bei der Adresse 01761234567890.a1b2c3d4e5f6g7h8@gateway.seven.io ist also a1b2c3d4e5f6g7h8 der Token und 01761234567890 der Prefix.

Kurzadresse ohne Token

Ist in der Konfiguration die Option Adresse ohne Token aktiv (möglich, sobald die DMARC-Prüfung greift, siehe Sicherheit), darf der Token entfallen: Eine Mail an 01761234567890@gateway.seven.io ordnen wir dann allein über Ihre Absenderadresse der Konfiguration zu, der gesamte lokale Teil der Adresse ist der Prefix. Dabei zählen nur nachgewiesene Absender (siehe Sicherheit). Führt mehr als eine Konfiguration denselben nachgewiesenen Absender, greift keine davon; eine nachgewiesene Adresse hat dabei Vorrang vor einer nachgewiesenen Domain-Freigabe. Die Token-Adresse funktioniert in jedem Fall weiter.

Einrichtung in fünf Schritten

Der Dialog unter Entwickler > API Zugänge führt Sie durch die fünf Schritte einer Konfiguration. Gespeichert wird im letzten Schritt, und zwar erst, nachdem eine Test-Mail von einem der erlaubten Absender eingegangen ist.

Variablen

In den Mustern stehen Ihnen folgende Variablen zur Verfügung. Die Liste ist abschließend, weitere Variablen gibt es nicht.

Basis

Erweitert: {{delay}}, {{type}}, {{label}}, {{foreign_id}}, {{unicode}}, {{flash}}, {{performance_tracking}}, {{get_replies}}

Bedeutung und erlaubte Werte dieser Variablen sind im Abschnitt Klassisches Format unter Parameter beschrieben und gelten hier unverändert. {{type}} überschreibt für die einzelne Mail den in der Konfiguration eingestellten Typ. {{get_replies}} nimmt yes oder no: mit yes versenden wir die Nachricht von einer antwortfähigen Rufnummer, damit der Empfänger direkt antworten kann; ein gesetzter Absender wird dadurch ersetzt.

WhatsApp: {{template}}, {{template_lang}}, {{header}}, {{body}}, {{buttons}}, {{media_url}}, {{media_type}}, {{caption}}

Diese Variablen füllen die Felder einer WhatsApp-Nachricht; ihre Bedeutung ist im Abschnitt WhatsApp (WA) beschrieben.

Die Authentifizierung läuft über Ihre Absenderadresse und den Token in der Adresse, einen Key gibt es nicht.

Jede Variable darf über alle drei Muster hinweg höchstens einmal vorkommen. {{text}} muss in einem der Muster gefangen werden, {{to}} entweder gefangen oder über Empfänger fest gesetzt sein.

So werten wir die Mail aus

• Das Muster für den Adress-Prefix muss den gesamten Prefix abdecken.
• In Betreff und Body suchen wir das Muster: der Literaltext muss vorkommen, die Variablen fangen den Text dazwischen ein.
• Ein leeres Muster bedeutet, dass dieser Teil der Mail ignoriert wird.
• Eine gefangene Absenderkennung hat Vorrang vor Absender der Nachricht, ein gefangener Empfänger vor Empfänger fest.
• Passt ein Muster nicht auf den zugehörigen Teil der Mail, wird die Nachricht nicht versendet.

Sicherheit

Die Absender-Verifizierung gilt unverändert: Wir akzeptieren ausschließlich Mails von einer der Absenderadressen, die Sie in der jeweiligen Konfiguration hinterlegt haben, beziehungsweise von einer Adresse einer dort hinterlegten Domain (*@domain).

DMARC-Prüfung

Sobald jeder Absender einer Konfiguration nachgewiesen ist, greift für sie automatisch die DMARC-Prüfung, und zwar in dem Moment, in dem der letzte Nachweis eingeht; ein Schalter ist dafür nicht nötig. Dann nehmen wir eine Mail nur an, wenn die Absenderdomain (die Domain der From-Adresse) die DMARC-Prüfung auf unserem Gateway besteht. Voraussetzung ist ein DMARC-Eintrag Ihrer Domain zusammen mit SPF oder DKIM; eine Domain ohne DMARC-Eintrag besteht die Prüfung nie. Weiterleitungen sind unkritisch, solange die DKIM-Signatur erhalten bleibt.

Eine Absenderadresse weisen Sie nach, indem Sie von ihr eine Test-Mail an die Test-Adresse der Konfiguration schicken, die die DMARC-Prüfung besteht. Eine Domain-Freigabe (*@domain) weisen Sie über einen TXT-Eintrag seven-mail-api-verify=TOKEN auf der Domain nach; zusätzlich muss die Domain (oder eine übergeordnete) einen DMARC-Eintrag haben. Wir prüfen beides täglich und nehmen den Nachweis zurück, wenn der TXT-Eintrag einige Tage fehlt. Eine Konfiguration mit aktiver DMARC-Prüfung nimmt keinen nicht nachgewiesenen Absender mehr auf; für Absender ohne DMARC legen Sie eine zweite Konfiguration an. Die Adresse ohne Token ist eine eigene Option, die erst mit aktiver DMARC-Prüfung wählbar ist; wer Token und DMARC kombinieren möchte, lässt sie aus. Für Freemail-Domains ist keine Domain-Freigabe möglich, und eine Absenderadresse, die in einem Konto nachgewiesen ist, kann kein anderes Konto mehr hinterlegen.

Eine abgelehnte Mail erscheint mit dem Code 904 in Ihrem Debugger. Eine Fehlermail geht in diesem Fall ausschließlich an die hinterlegte Error-Mail-Adresse und nie an den Absender der Mail, da dieser gefälscht sein könnte.

Beispiele

Standardkonfiguration

Ohne Anpassung der Muster wird der gesamte Body zum Nachrichtentext. Der Empfänger steht in der Konfiguration, die Mail geht an die nackte Adresse.

Ergebnis: eine SMS an 01761234567890 mit dem Text "Ihr Paket ist unterwegs." Der Betreff wird ignoriert.

Empfänger in der Adresse

Soll jede Mail an eine andere Rufnummer gehen, fangen Sie den Empfänger mit {{to}} im Prefix der Adresse. Ein fester Empfänger ist dann nicht nötig.

Ergebnis: eine SMS an 01761234567890 mit dem Text "Ihr Paket ist unterwegs."

Meldung im Betreff, fester Empfänger

Ein Monitoring-Tool schickt seine Meldung im Betreff an eine feste Adresse. Der Empfänger steht in der Konfiguration.

Ergebnis: eine SMS an 01761234567890 mit dem Text "CPU-Last kritisch auf srv-07".

Muster mit Ankern

Steht in der Mail mehr als nur der Nachrichtentext, grenzen Sie ihn mit Literaltext ab. Hier fassen zwei Klammerpaare den Text ein, danach folgt der Versandzeitpunkt.

Ergebnis: eine SMS an 01761234567890 mit dem Text "Ihre Bestellung ist unterwegs.", geplant für den 15.01.2027 um 08:00 Uhr. Der Zeitpunkt im Beispiel steht stellvertretend für einen Zeitpunkt in der Zukunft, den Ihre Anwendung selbst setzt.

Fehlerbehandlung

Passt ein Muster nicht auf den zugehörigen Teil der Mail oder bleibt der Empfänger leer, wird die Nachricht nicht versendet. Sie erhalten eine Fehlermail mit dem Grund, sofern Sie die Option „Benachrichtigen bei Fehlern“ aktiviert haben. Greift die DMARC-Prüfung, gilt das Gleiche für Mails, deren Absenderdomain die DMARC-Prüfung nicht besteht; diese Fehlermail geht nur an die Error-Mail-Adresse.

Einrichtung

In Ihrem Login unter Entwickler > API Zugänge verwalten Sie Ihre Konfigurationen. Über den Button Neu anlegen oben rechts und die Kachel Mail API legen Sie eine neue an; der Dialog führt Sie durch die fünf oben beschriebenen Schritte. Sie können beliebig viele Konfigurationen anlegen, jede mit eigenen erlaubten Absendern, eigener fester Adresse und eigenen Mustern. Speichern ist erst nach einer Test-Mail von einem der erlaubten Absender möglich, danach ist die Konfiguration sofort nutzbar.

Die übergreifenden Einstellungen für die Mail API finden Sie unter Entwickler > Einstellungen im Bereich Mail API.

Mail API Einstellungen

• Maximale Zeichenanzahl: Legen Sie eine maximale Zeichenzahl fest, um zu lange Nachrichten durch das Mitsenden von Signaturen zu vermeiden. Geben Sie 0 ein, um diese Funktion zu deaktivieren.
• Signatur entfernen: Ist dies aktiviert, versucht die API automatisch zitierten Text in der Mail zu entfernen.
• Benachrichtigung bei Fehler: Diese Option legt fest, ob Sie bei etwaigen Fehlern eine Benachrichtigung per Mail erhalten möchten. Wenn z.B. der Versand der Nachricht fehlschlägt, ein Muster nicht auf Ihre Mail passt oder Angaben wie der Empfänger fehlen, schicken wir Ihnen direkt eine Mail mit einer Information zum Fehler zu. Beim Anlegen einer Konfiguration können Sie optional eine alternative Mailadresse angeben, auf die Sie die Fehlermeldungen erhalten möchten.
• HTTP-Push bei Fehler: Ist dies aktiviert, melden wir fehlerhafte Mails zusätzlich per HTTP an Ihre Webhooks, mit Fehlercode und Fehlerbeschreibung.
• Absender in SMS einfügen: Hier können Sie einstellen, ob Sie einen Teil der Mailadresse am Anfang Ihrer Nachricht mitsenden möchten. Sie können zwischen drei Möglichkeiten wählen:

Klassisches Format

Konfigurationen, die vor Einführung der festen Adresse angelegt wurden, arbeiten im klassischen Format: der Empfänger steht im lokalen Teil der Adresse, die Steuerparameter stehen im Betreff. Im Dashboard sind sie als Legacy gekennzeichnet und funktionieren unverändert und unbefristet weiter. Neue Konfigurationen nutzen Mail-Muster.

Aufbau der Mail

Mails an eine Legacy-Konfiguration haben den nachfolgend beschriebenen Aufbau. Neue Konfigurationen verwenden stattdessen die feste Adresse mit Mail-Mustern.

Empfänger

Um eine Nachricht über die Mail API zu versenden, schicken Sie eine Mail an empfaenger@gateway.seven.io und ersetzen dabei empfaenger durch die Empfängernummer oder durch den Kontaktnamen aus Ihrem Adressbuch.

Wenn Sie z.B. eine Nachricht an die Nummer 01761234567890 senden möchten, muss der Empfänger 01761234567890@gateway.seven.io lauten.

Betreff

Im Betreff geben Sie die benötigten Parameter zur Steuerung des Nachrichtenversands ein. Diese sollten jeweils durch ein Leerzeichen getrennt sein. Um einen Parameter zu setzen, schreiben Sie den Namen des Parameters, gefolgt von einem Gleichheitszeichen und dem Wert des Parameters.

So wird z.B. mit einParameter=einWert der Parameter einParameter auf einWert gesetzt. Sofern der Parameter Leerzeichen enthält, sollten Sie diesen in doppelte Anführungszeichen " einfassen – zum Beispiel einParameter="Ein Wert mit Leerzeichen".

Inhalt

Der Nachrichtentext muss im Body der E-Mail gesendet werden. Das Gateway verwendet hierzu zuerst den text/plain Teil der Mail. Sollte die Mail nur einen text/html Teil ohne Textalternative enthalten, wird versucht diesen zu parsen und den Textteil aus dem HTML Inhalt zu entnehmen. Naturgemäß funktioniert diese Methode nicht immer wie gewünscht.

Sie können den Nachrichtentext optional mit ## einfassen um zu verhindern, dass leere Zeilen oder die Signatur der Mail mit in der Nachricht stehen. Der Text würde dann so aussehen: ##Dies ist der Text## - nur der Teil zwischen ##...## wird in der Nachricht gesendet.

Parameter

Alle Parameter werden wie oben genannt im Betreff der Mail angegeben. Sollte es Ihnen nicht möglich sein, den Betreff der Mail zu ändern, können Sie die Parameter auch in der Empfängeradresse wie folgt angeben:

• 01761234567890.from=ZahnPraxis@gateway.seven.io
• 01761234567890.from=ZahnPraxis.type=rcs@gateway.seven.io
• key=MAIL_API_KEY.from=ZahnPraxis.to=01761234567890@gateway.seven.io

Hier eine Übersicht der möglichen Parameter:

WhatsApp (WA)

Die Mail API versendet auch WhatsApp-Nachrichten. In einer Konfiguration mit Mail-Mustern stellen Sie dazu den Typ auf WhatsApp und tragen Ihre WhatsApp Service Frontend ID (Format: WA-XXXXXXXX) als Absender der Nachricht ein; in einer Legacy-Konfiguration setzen Sie type=WA und den Parameter from. Die ID finden Sie in Ihrem seven.io Dashboard unter WABA → Services. Die folgenden Felder stehen in beiden Fällen zur Verfügung: als Variablen in den Mustern oder als Parameter im Betreff.

WhatsApp Nachrichtentypen

WhatsApp unterstützt drei Nachrichtentypen, die automatisch anhand der Parameter bestimmt werden:

wenn template != null:
    → Template-Nachricht
sonst wenn media_url != null:
    → Media-Nachricht
sonst:
    → Text-Nachricht (E-Mail Body)

Template-Nachrichten

Template-Nachrichten werden für Nachrichten außerhalb des 24h-Fensters benötigt und müssen vorher von WhatsApp genehmigt werden.

Media-Nachrichten

Media-Nachrichten können nur innerhalb des 24h Conversation Windows gesendet werden.

Text-Nachrichten

Für einfache Textnachrichten innerhalb des 24h-Fensters wird der E-Mail Body als Nachricht verwendet.

WhatsApp Beispiele (klassisches Format)

1. Template-Nachricht (außerhalb 24h Window)

An: 491512345678.MYKEY.type=WA.from=WA-5AAB129C.template=order_confirmation.template_lang=de_DE.body=Max,12345@gateway.seven.io

2. Template mit Header-Bild

An: 491512345678.MYKEY.type=WA.from=WA-5AAB129C.template=promo_image.header=https://example.com/promo.jpg.body=20%25-Rabatt@gateway.seven.io

3. Text-Nachricht (innerhalb 24h Window)

An: 491512345678.MYKEY.type=WA.from=WA-5AAB129C@gateway.seven.io

4. Bild senden (innerhalb 24h Window)

An: 491512345678.MYKEY.type=WA.from=WA-5AAB129C.media_type=image.media_url=https://example.com/produkt.jpg.caption=Ihr-Produkt@gateway.seven.io

5. Dokument senden

An: 491512345678.MYKEY.type=WA.from=WA-5AAB129C.media_type=document.media_url=https://example.com/rechnung.pdf.caption=Ihre-Rechnung@gateway.seven.io

Sicherheit

Der Transportweg zwischen den einzelnen SMTP Servern bzw. dem SMTP Client ist zwar in aller Regel per TLS verschlüsselt. Aus mehreren Gründen ist allerdings eine Verschlüsselung der Mail sinnvoll, weshalb die Mail API Verschlüsselung per PGP und per S/MIME unterstützt:

1. Vertraulichkeit: PGP und S/MIME verschlüsseln den Inhalt von E-Mails, sodass nur der beabsichtigte Empfänger sie entschlüsseln und lesen kann. Dadurch wird die Vertraulichkeit der Kommunikation gewährleistet.

2. Authentifizierung: Beide Standards ermöglichen es, die Identität des Absenders zu überprüfen. Digitale Signaturen, die mit dem privaten Schlüssel des Absenders erstellt werden, ermöglichen es dem Empfänger, sicherzustellen, dass die E-Mail tatsächlich von der angegebenen Quelle stammt und nicht manipuliert wurde.

3. Integrität: PGP und S/MIME bieten Mechanismen zur Überprüfung der Integrität von E-Mails. Durch digitale Signaturen kann der Empfänger sicherstellen, dass der Inhalt der E-Mail seit dem Versenden nicht verändert wurde.

4. Abwehr von Man-in-the-Middle-Angriffen: Durch die Verschlüsselung und Authentifizierung helfen PGP und S/MIME dabei, Man-in-the-Middle-Angriffe zu verhindern, bei denen ein Angreifer den Datenverkehr abfängt, manipuliert und dann weiterleitet, ohne dass die beteiligten Parteien es bemerken.

Insgesamt sind PGP und S/MIME daher sinnvoll, um die Sicherheit, Vertraulichkeit und Integrität von E-Mail-Kommunikation zu gewährleisten, insbesondere in Umgebungen, in denen sensible oder vertrauliche Informationen ausgetauscht werden.

Für einen verschlüsselten Versand der Mails laden Sie bitte das jeweilige Zertifikat herunter und installieren Sie dieses in Ihrem System. Da PGP und S/MIME Zertifikate nur an eine einzige Mailadresse gebunden sein können, senden Sie Ihre Mails bitte an die unten zum Zertifikat angegebene E-Mail-Adresse.

Den Empfänger und weitere Angaben machen Sie dabei wie im klassischen Format über Parameter im Betreff, z.B. to=017612345678.

Hier können Sie das jeweilige Zertifikat herunterladen:

DMARC, DKIM, SPF

DKIM, SPF und DMARC sind Mechanismen zur Verbesserung der E-Mail-Sicherheit. Sie helfen dabei, die Authentizität von E-Mails zu überprüfen, Spam und Phishing zu bekämpfen sowie die Zustellbarkeit von E-Mails zu verbessern.

Unser Gateway prüft jede eingehende Mail gegen SPF, DKIM und DMARC. Standardmäßig ist das Ergebnis nur informativ: Maßgeblich für die Annahme bleibt der Abgleich mit den hinterlegten Absenderadressen. Erst wenn die DMARC-Prüfung Ihrer Mail-API-Konfiguration greift (alle Absender nachgewiesen), werden Mails abgelehnt, deren Absenderdomain die DMARC-Prüfung nicht besteht (Code 904, siehe oben unter Sicherheit). Abgelehnte Mails können Sie in Ihrem Debugger einsehen.

Beispiele für das klassische Format

Erstes Beispiel

Im ersten Beispiel wird eine SMS an die Rufnummer 0163123456789 von dem Absender ZahnPraxis gesendet. Der Schlüssel lautet in diesem Fall email2sms_key.

Der Text, der in der SMS übertragen werden soll, lautet:

Hallo Herr Schubert, hiermit möchten wir Sie an Ihren Termin am 20. Januar bei uns in der Praxis erinnern. Wir freuen uns auf Sie! Bis dahin, Ihre Zahnarztpraxis

Zweites Beispiel

In diesem zweiten Beispiel wird eine SMS an den Kontakt Bartscher vom Absender Optiker gesendet. Die Vorgabe zur Nummer 0163123456789, die im Empfänger der Mail steht, wird durch den Parameter to überschrieben. Der Schlüssel lautet hier 123456789.

Der Text, der in der SMS übertragen werden soll, lautet:

Hallo Frau Bartscher, Ihre Brille ist fertig! Bitte holen Sie diese demnächst bei uns ab. Wir freuen uns auf Sie! Bis dahin, Ihre Optiker – die Signatur der Mail unten wird nicht in der SMS mitgesendet, da der Text durch ## eingefasst ist.

Drittes Beispiel

In diesem Beispiel wird eine SMS an die Rufnummer 0163123456789 gesendet. Die Einstellungen für den Absender werden aus den Voreinstellungen Ihres Accounts verwendet unter Einstellungen > SMS. Der Schlüssel ist hier direkt im Empfänger der Mail integriert und zu abcd123456 gesetzt.

Der Text, der in der SMS übertragen werden soll, lautet:

Hallo Frau Bartscher, Ihre Brille ist fertig! Bitte holen Sie diese demnächst bei uns ab. Wir freuen uns auf Sie! Bis dahin, Ihre Optiker

Die Signatur der Mail unten wird nicht in der SMS mitgesendet, da der Text durch ## eingefasst ist.

Legacy

Aus Gründen der Abwärtskompatibilität bleibt die Mail API unter der alten Empfängeradresse email2sms@sms77.de für Mails im damaligen Format weiterhin erhalten. Die Mails werden weiterhin wie gewohnt bearbeitet werden. Wir empfehlen den Wechsel auf eine Konfiguration mit fester Adresse und Mail-Mustern, um den vollen Funktionsumfang nutzen zu können.