Mail API

Die Mail API ermöglicht Ihnen den Versand von SMS, RCS und bald auch Voice-Nachrichten über seven per Mail. Senden Sie eine Mail an das Gateway, welche dann von uns automatisch zur einer Nachricht umgewandelt wird. Über zahlreiche Parameter können Sie den Versand gezielt steuern und auch an Kontakte oder Gruppen Nachrichten senden.

Einrichtung

In Ihrem Login im Bereich Entwickler unter Mail API können Sie die API für Ihren Account einrichten. Dabei können Sie beliebig viele Absenderadressen mit jeweils unterschiedlichem Key angeben.

  1. 1

    Absenderadresse einrichten

    Über das grüne + - Icon unten rechts im Bereich Mail API gelangen Sie zum Fenster, in dem Sie eine neue Absenderadresse anlegen können.

  2. 2

    Schlüssel festlegen

    Sie sollten sich für jede Mailadresse einen Key aussuchen, der den Versand sicherer macht. Sie können sich den Key frei aussuchen, allerdings sind nur Klein- und Großbuchstaben, Zahlen und die Sonderzeichen Bindestrich, Unterstrich und Dollarzeichen erlaubt.

  3. 3

    Fehlerbehandlung

    Sie können hier auch eine optionale Mailadresse zum Empfang von Fehlermeldungen angeben. Wenn Sie diese nicht angeben, erhalten Sie die Fehlermeldungen auf die Absenderadresse, wenn Sie die Funktion „Benachrichtigen bei Fehlern“ in den Einstellungen aktivieren (siehe unten).Neu eingerichtete Absender sind sofort nach dem Speichern nutzbar.

  4. 4

    Einstellungen

    Über einen Klick auf die blauen Zahnräder gelangen Sie zu den Einstellungsmöglichkeiten für die Mail API.

Einstellungen Mail API

  • Maximale Länge: 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.

  • Zitate entfernen: Ist dies aktiviert, versucht die API automatisch zitierten Text in der Mail zu entfernen.

  • Benachrichtigen 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 oder Daten wie Nummer, Key, etc in Ihrer Email falsch angegeben wurden oder fehlen, schicken wir Ihnen direkt eine Mail mit einer Information zum Fehler zu. Beim Anlegen einer neuen Absenderadresse können Sie optional eine alternative Mailadresse angeben, auf die Sie die Fehlermeldungen erhalten möchten.

  • Absender der Mail in Text 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:

    EinstellungenErklärung
    Vollständige AdresseFügt die gesamt Adresse ein, z.B. "einuser@domain.de"
    Lokaler Part der Adressez.B. wird bei einuser@domain.de „einuser“ eingefügt
    NeinSendet die Absenderadresse nicht mit

Nachricht senden

Aufbau der Mail

Bitte verwenden Sie das nachfolgend beschriebene Format für Ihre Mails an unser Gateway. Sollte Ihre Anwendung nicht dahingehend anpassbar sein, dass die Mails entsprechend dieses Formats gesendet werden können, kontaktieren Sie uns – die Mail API ist flexibel anpassbar!

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 Email 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:

  • Name
    key
    Type
    string
    Optional
    Optional
    Description
    Der Zugangs-Key, welchen Sie in Ihren Mail-API Einstellungen für die jeweilige Absender-Email angegeben haben.
  • Name
    from
    Type
    string
    Optional
    Optional
    Description
    Der Absender der Nachricht. Sofern hier nichts angegeben wurde, wird der Standard Absender aus Ihren SMS Einstellungen verwendet. Möglich sind bis zu 11 alphanumerische oder bis zu 16 numerische Zeichen.
  • Name
    to
    Type
    string
    Optional
    Optional
    Description
    Der Empfänger der Nachricht. Dieser Parameter überschreibt, falls angegeben, den Empfänger, welcher in der Empfängeradresse der Mail angegeben wurde. Somit könnten Sie z.B. eine Mail an acme-inc@gateway.seven.io mit Parameter to=0176123456789 senden. Die Nachricht wird an 0176123456789 gesendet.
  • Name
    label
    Type
    string
    Optional
    Optional
    Description
    Setzen Sie optional für jede Nachricht ein eigenes Label, um diese in Ihren Statistiken zuordnen zu können. Wenn nicht angegeben, wird automatisch der Absender der Email als Label verwendet. Erlaubte Zeichen: a-z, A-Z, 0-9, .-_@
  • Name
    text
    Type
    string
    Optional
    Optional
    Description
    Sofern es Ihnen nicht möglich ist, den Nachrichtentext im Inhalt der Mail zu platzieren, können Sie diesen über den text Parameter im Betreff eingeben.
  • Name
    flash
    Type
    boolean
    Optional
    Optional
    Description
    Senden Sie eine Flash SMS, welche direkt im Display des Empfängers angezeigt und nicht gespeichert wird. Nur für den Nachrichtentyp SMS.
  • Name
    unicode
    Type
    boolean
    Veraltet
    Veraltet
    Optional
    Optional
    Description
    Erlaubt die Kodierung der Nachricht als Unicode oder forciert GSM 03.38.
  • Name
    performance_tracking
    Type
    boolean
    Optional
    Optional
    Description
    Aktiviert unseren URL Shortener und das Performance Tracking für im Text gefundene Links.
  • Name
    foreign_id
    Type
    string
    Optional
    Optional
    Description
    Geben Sie Ihre eigene ID für diese Nachricht an. Sie erhalten die foreign_id wiederum zurück bei Callbacks für Statusberichte etc. Max. 64 Zeichen, erlaubte Zeichen: a-z, A-Z, 0-9, .-_@.
  • Name
    delay
    Type
    string
    Optional
    Optional
    Description
    Plant den zeitversetzten Versand der Nachricht in der Zukunft. Geben Sie hier entweder einen Unix Timestamp oder den Zeitpunkt im Format JJJJ-MM-TT hh:mm:ss an.
  • Name
    type
    Type
    enum
    Optional
    Optional
    Description
    Legen Sie den Nachrichtentyp fest, den Sie versenden möchten. Möglich sind hier sms (standard), rcs und demnächst auch voice.

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üsseung 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 Email-Adresse.

Daten wie den Empfänger der Nachricht müssen Sie im Betreff über die jeweiligen Parameter angeben, wie z.B. to=017612345678.

Dieses Verfahren ist nicht sicher, da die Daten in den Headern der Mail unverschlüsselt gesendet werden. Wir arbeiten bereits an einer alternativen Lösung.

Hier können Sie das jeweilige Zertifikat herunterladen:

PGP

Zertifikat herunterladen

Mail Adresse: gateway@gateway.seven.io

S/MIME

Zertifikat herunterladen

Mail Adresse: mail@gateway.sms77.io

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.

Die Mail API lehnt Mails ab, wenn sie nicht den Authentifizierungsstandards entsprechen, die durch Ihre Konfiguration zu DKIM, SPF und DMARC festgelegt sind. Dies kann zum Beispiel der Fall sein, wenn eine E-Mail keine gültige DKIM-Signatur aufweist, die IP-Adresse des Absenders nicht in den SPF-Einträgen autorisiert ist oder die DMARC-Richtlinien des Domaininhabers eine Ablehnung nicht authentifizierter E-Mails vorsehen.

Bitte beachten Sie dies bei der Implementierung der Mail API. Abgelehnte Mails können Sie in Ihrem Debugger einsehen.

Beispiele

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.

Mail-zu-SMS erstes Beispiel

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.

Mail-zu-SMS zweites Beispiel

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.

Mail-zu-SMS drittes Beispiel

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 jedoch den Wechsel auf diese neue API, um den vollen Funktionsumfang nutzen zu können.

Zuletzt aktualisiert: Vor 1 Monat