Einrichtung der Mail API

Mit der Mail API versenden Sie Nachrichten per E-Mail: Sie schicken eine Mail an die feste Adresse Ihrer Konfiguration, seven wertet sie anhand Ihrer Muster aus und versendet das Ergebnis als SMS, RCS, WhatsApp- oder Voice-Nachricht. Wo in der Mail Empfänger, Text und Absender stehen, legen Sie einmalig in der Konfiguration fest. So passt sich die Mail API an Ihre Anwendung an, zum Beispiel an ein Monitoring-Tool, einen Shop oder Ihr Mailprogramm.

Wie Sie danach Nachrichten verschicken, lesen Sie in den Artikeln Versand von SMS via Email und Versand von RCS via Email.

Mail-API-Konfiguration anlegen

Öffnen Sie Entwickler -> API-Zugänge. Die Liste zeigt alle REST-API-Keys, Mail-API-Konfigurationen und SMPP-Verbindungen. Klicken Sie oben rechts auf Neu anlegen und wählen Sie Mail API.

Liste der API-Zugänge mit einer Mail-API-Konfiguration und dem Button Neu anlegen (englische Dashboard-Ansicht)

Der Dialog Mail API Adresse anlegen führt Sie in fünf Schritten durch die Konfiguration. Sie können beliebig viele Konfigurationen anlegen, jede mit eigenen Absendern, eigener fester Adresse und eigenen Mustern.

Schritt 1: Zugang

Tragen Sie unter Erlaubte Absender die Mail-Adressen ein, von denen Sie senden: eine Adresse pro Zeile, bis zu zehn pro Konfiguration. Mails von anderen Adressen nimmt das Gateway nicht an. Mit *@ihre-domain.de geben Sie alle Adressen einer Domain frei.

Schritt Zugang mit zwei erlaubten Absendern (englische Dashboard-Ansicht)

Nicht erlaubt sind:

Adressen auf seven-eigenen Domains (seven.io, sms77.io, sms77.de und deren Subdomains)
Domain-Freigaben (*@domain) für Freemail-Anbieter wie Gmail oder GMX
Adressen, die bereits in einem anderen seven-Konto nachgewiesen sind

Diese Prüfungen laufen schon beim Klick auf Weiter, damit Sie Fehler direkt am Eingabefeld sehen.

Schritt 2: Muster

Hier beschreiben Sie, wie Ihre Mails aussehen. Literaltext im Muster muss genau so in der Mail vorkommen und dient als Anker, Variablen in doppelten geschweiften Klammern fangen den Text dazwischen ein.

Schritt Muster mit dem Muster {{to}} für den Adress-Prefix und {{text}} für den Body (englische Dashboard-Ansicht)

Muster Adress-Prefix (Standard: leer): gilt für den Teil der Adresse vor dem Token. Mit {{to}} geht eine Mail an 4917612345678.TOKEN@gateway.seven.io an genau diese Rufnummer. Bleibt das Feld leer, schicken Sie Ihre Mails an die Adresse ohne Prefix und der Empfänger kommt aus den Einstellungen (Schritt 3).
Muster Betreff (Standard: leer): leer bedeutet, dass der Betreff ignoriert wird.
Muster Body (Standard: {{text}}): mit dem Standard wird der gesamte Mailtext zum Nachrichtentext.

Die wichtigsten Variablen sind {{to}} (Empfänger: Rufnummer, Kontakt oder Gruppe), {{text}} (Nachrichtentext) und {{from}} (Absenderkennung). Unter Erweitert und WhatsApp finden Sie weitere Variablen, z.B. {{delay}} für den zeitversetzten Versand oder {{label}}. Die vollständige Liste steht in der Mail-API-Dokumentation.

Beispiel: Das Muster Body (({{text}})) delay={{delay}} passt auf die Mail ((Ihre Bestellung ist unterwegs.)) delay=2027-01-15 08:00:00 und plant die Nachricht für den 15.01.2027 um 8 Uhr ein.

Schritt 3: Einstellungen

Unter Defaults legen Sie fest, was gilt, wenn die Muster nichts liefern:

Empfänger fest: greift, wenn kein Muster {{to}} fängt, und ist dann Pflicht.
Absender der Nachricht: greift, wenn kein Muster {{from}} fängt. Leer bedeutet der Standardabsender Ihres Kontos.
Typ: SMS, RCS, WhatsApp oder Voice.

Unter Optionen tragen Sie optional eine Error-Mail ein, an die Fehlermeldungen gehen sollen.

Schritt Einstellungen mit Empfänger fest, Absender der Nachricht, Typ und Error-Mail (englische Dashboard-Ansicht)

Schritt 4: Vorschau

Bevor Sie speichern können, prüfen Sie Ihre Muster an einer echten Mail. Jede Konfiguration hat dafür eine Test-Adresse mit dem Zusatz -test, also TOKEN-test@gateway.seven.io (mit Prefix z.B. 4917612345678.TOKEN-test@gateway.seven.io). Über Beispiel-Mail öffnen bereitet Ihr Mailprogramm eine passende Mail vor.

Schicken Sie die Test-Mail von einem der erlaubten Absender. Sobald sie eintrifft, sehen Sie die erkannten Variablen und die Nachricht, die daraus entstehen würde. Mails an die Test-Adresse lösen keinen Versand aus.

Schritt Vorschau mit eingegangener Test-Mail, erkannten Variablen und Ergebnis (englische Dashboard-Ansicht)

Wichtig:

Ohne Test-Mail lässt sich die Konfiguration nicht speichern, auch nicht beim späteren Bearbeiten.
Eine Test-Mail von einer Adresse, die nicht in der Liste der erlaubten Absender steht, wird angezeigt, zählt aber nicht. Senden Sie in diesem Fall vom richtigen Konto aus.
Kommen mehrere Test-Mails an, ist die neueste passende die Vorschau. Ältere lassen sich aufklappen.
Blockiert Ihr Netzwerk die Live-Verbindung des Dashboards, ruft der Dialog eingegangene Test-Mails automatisch alle paar Sekunden ab. Über Test-Mail jetzt abrufen stoßen Sie das sofort an.

Schritt 5: Sicherheit

Im letzten Schritt sehen Sie die feste Adresse der Konfiguration (TOKEN@gateway.seven.io), den Absender-Nachweis für jeden erlaubten Absender und den Status der DMARC-Prüfung. Mit Speichern schließen Sie die Einrichtung ab, die Konfiguration ist sofort nutzbar.

Schritt Sicherheit mit fester Adresse, einem nachgewiesenen Absender und einer Domain mit ausstehendem TXT-Eintrag (englische Dashboard-Ansicht)

Absender nachweisen und DMARC-Prüfung

Das Gateway nimmt grundsätzlich nur Mails von den erlaubten Absendern an. Zusätzlich können Sie nachweisen, dass Ihnen die Absender wirklich gehören. Sobald alle Absender einer Konfiguration nachgewiesen sind, schaltet sich die DMARC-Prüfung automatisch ein. Einen Schalter dafür gibt es nicht.

So weisen Sie Absender nach:

Einzelne Adresse: Schicken Sie von dieser Adresse eine Test-Mail an die Test-Adresse, die die DMARC-Prüfung besteht. Die Test-Mail aus Schritt 4 zählt bereits als Nachweis, wenn sie DMARC besteht.
Domain-Freigabe (*@domain): Legen Sie auf der Domain einen TXT-Eintrag seven-mail-api-verify=TOKEN an und klicken Sie auf DNS prüfen. Zusätzlich braucht die Domain (oder eine übergeordnete Domain) einen DMARC-Eintrag. seven prüft beides täglich und nimmt den Nachweis zurück, wenn der TXT-Eintrag einige Tage fehlt.

Ist die DMARC-Prüfung aktiv, nimmt das Gateway nur noch Mails an, deren Absenderdomain die DMARC-Prüfung besteht. Voraussetzung ist ein DMARC-Eintrag Ihrer Domain zusammen mit SPF oder DKIM. Weiterleitungen sind unkritisch, solange die DKIM-Signatur erhalten bleibt. Abgelehnte Mails erscheinen mit dem Code 904 im Debugger. Die Fehlermail geht dann ausschließlich an die Error-Mail-Adresse, nie an den Absender, denn der könnte gefälscht sein.

Besteht eine Test-Mail die Prüfung nicht, nennt der Dialog den Grund, z.B. dass die Absenderdomain keinen DMARC-Eintrag hat, dass weder SPF noch DKIM zur Absenderdomain passen oder dass sich das Ergebnis auf eine andere Domain als die From-Adresse bezieht.

Gut zu wissen: Einer Konfiguration mit aktiver DMARC-Prüfung können Sie keine nicht nachgewiesenen Absender mehr hinzufügen. Für Absender ohne DMARC legen Sie eine zweite Konfiguration an.

Adresse ohne Token

Mit aktiver DMARC-Prüfung können Sie im Schritt Sicherheit zusätzlich die Option Adresse ohne Token zusätzlich erlauben aktivieren. Dann genügt der Prefix als ganze Adresse, z.B. 4917612345678@gateway.seven.io. seven ordnet die Mail allein über den nachgewiesenen Absender Ihrer Konfiguration zu. Die Adresse mit Token funktioniert weiterhin. Wer Token und DMARC-Prüfung kombinieren möchte, lässt die Option aus.

Schritt Sicherheit mit aktiver DMARC-Prüfung und aktivierter Option Adresse ohne Token (englische Dashboard-Ansicht)

Nutzt derselbe nachgewiesene Absender mehrere Konfigurationen mit dieser Option, wird die Mail nicht zugeordnet und nicht versendet.

Weitere Mail-API-Einstellungen

Öffnen Sie Entwickler -> Einstellungen und klappen Sie den Bereich Mail API auf. Diese Einstellungen gelten für alle Mail-API-Konfigurationen.

Bereich Mail API in den Entwickler-Einstellungen (englische Dashboard-Ansicht)

Maximale Zeichenanzahl: begrenzt die Länge der Nachricht, damit versehentlich mitgesendete Signaturen oder Footer die Kosten nicht in die Höhe treiben. 0 deaktiviert das Limit.
Signatur entfernen: filtert zitierten Text (> wie diese Zeilen) vor dem Versand heraus.
Benachrichtigung bei Fehler / HTTP-Push bei Fehler: Sie werden per E-Mail bzw. HTTP-Push informiert, wenn eine Mail nicht verarbeitet werden kann, etwa weil ein Muster nicht passt oder der Empfänger fehlt.
Absender in SMS einfügen: stellt der Nachricht die Absenderadresse der Mail voran, wahlweise als Komplette Adresse (einuser@domain.de), als Lokaler Teil (vor @) (einuser) oder gar nicht (Nicht anhängen).

Bestehende Konfigurationen (Legacy)

Konfigurationen, die vor Einführung der festen Adresse angelegt wurden, sind in der Liste mit Legacy gekennzeichnet. Sie arbeiten im klassischen Format weiter: Die Rufnummer steht vor @gateway.seven.io, Steuerparameter wie key=, from= oder type= stehen im Betreff. Legacy-Konfigurationen funktionieren unverändert und unbefristet, erlauben aber nur einen Absender und keine DMARC-Prüfung. Für neue Anwendungen empfehlen wir eine Konfiguration mit fester Adresse und Mustern.

Dokumentation

Vollständige Referenz mit allen Variablen, Beispielen und dem klassischen Format finden Sie in der Mail-API-Dokumentation.