Zum Inhalt springen

Funktionen

Transaktions-API

Ereignisgesteuerte E-Mails aus Ihrer Anwendung senden. Anders als Kampagnen gehen Transaktions-E-Mails in Echtzeit an jeweils einen Kontakt, und Notifuse legt den Kontakt beim Versand an oder aktualisiert ihn. Sie eignen sich für Benachrichtigungen, die Ihre Nutzer auslösen, und für automatisierte Abläufe.

Liste der Transaktionsbenachrichtigungen in der Konsole

Häufige Anwendungsfälle

- Password Reset
- Order Confirmation
- Welcome Email
- Account Deletion
- Purchase Receipt
- Shipping Notifications
- Account Verification
- Payment Confirmations

Die wichtigsten Funktionen

Automatische Kontaktverwaltung

  • Das Objekt contact in der Anfrage legt den Kontakt vor dem Versand an oder aktualisiert seine Felder, sodass seine Daten aktuell bleiben.
  • Vorlagendaten (data) werden nicht am Kontakt gespeichert. Ihre Schlüssel werden zu Vorlagenvariablen der obersten Ebene, und das gespeicherte Kontaktprofil steht unter contact bereit.

Um den Kontakt auf diese Weise zu aktualisieren, braucht es das Schreibrecht für Kontakte. Ohne dieses Recht legt ein Versand einen fehlenden Kontakt nur mit seiner E-Mail-Adresse an und ändert nie einen bestehenden (siehe Berechtigungen).

Anreicherung der Vorlagendaten

Wenn Sie eine Transaktions-E-Mail senden, geht Notifuse so vor:

  1. Legt den Kontakt an oder aktualisiert ihn und sucht ihn dann anhand der E-Mail-Adresse in Ihrem Arbeitsbereich
  2. Legt die Schlüssel von data auf die oberste Ebene der Vorlagenvariablen und das gespeicherte Profil des Kontakts unter contact
  3. Rendert die Vorlage mit den vollständigen Kontaktdaten
  4. Versendet die personalisierte E-Mail

Beispiel: Sendet Ihre API "data": {"order_id": "12345"} und enthält das Kontaktprofil {"first_name": "John", "last_name": "Doe"}, kann die Vorlage {{ order_id }} und {{ contact.first_name }} verwenden.

Deduplizierung mit External ID

  • Setzen Sie external_id, damit dieselbe Benachrichtigung nicht zweimal verschickt wird: Benachrichtigungen mit derselben external_id gehen nur einmal raus.
  • Verwenden Sie Ihre eigenen eindeutigen Kennungen (Bestell-IDs, Ereignis-IDs usw.).

Beispiel: Mit external_id: "order-12345" wird die Bestellbestätigung nur einmal zugestellt, auch wenn Ihr System sie mehrfach sendet.

Optionen für die Zustellung

Jeder Versand kann Folgendes festlegen:

  • Von Name: überschreibt den Standard-Anzeigenamen des Absenders
  • Betreff: überschreibt die Betreffzeile der Vorlage (unterstützt Liquid)
  • Antwort-an: legt eigene Antwortadressen fest
  • CC: fügt Empfänger in Kopie hinzu
  • BCC: fügt Empfänger in Blindkopie hinzu
  • Anhänge: hängt Dateien an die E-Mail an (PDFs, Bilder, Dokumente usw.)

Tracking

Öffnungen und Klicks richten sich nach den Einstellungen des Arbeitsbereichs und der Tracking-Einwilligung des Kontakts. Ein contact in der Anfrage kann tracking_opens_consent und tracking_clicks_consent mitbringen; beide werden mit der Quelle api erfasst, sofern Sie nicht tracking_consent_source senden. Jede Benachrichtigung kann das Tracking außerdem abschalten:

  • Kein Öffnungs- oder Klick-Tracking, UTM-Parameter behalten (tracking_mode: "no_tracking")
  • Für diese Benachrichtigung deaktiviert (tracking_mode: "disabled"): Links werden nie umgeschrieben und tragen keine Tracking- oder UTM-Parameter. Verwenden Sie diese Option für Links, die unverändert bleiben müssen, etwa Anmeldelinks

Überwachung in der Konsole

Die Seite Transaktional listet Ihre Benachrichtigungen mit ihren Statistiken der letzten 7, 30 oder 60 Tage auf, den heutigen Tag eingeschlossen:

  • Summen: versendete E-Mails, Zustellrate mit ihrer Veränderung gegenüber dem vorherigen Zeitraum, Öffnungs- und Klickraten der getrackten E-Mails, Fehlschläge und Bounces.
  • Eine Zeile pro Benachrichtigung: ihre Vorlage, versendete E-Mails, Zustell-, Öffnungs- und Klickrate, Fehlschläge, Bounce-Rate und der Zeitpunkt des letzten erfolgreichen Versands. Eine Zustellrate unter 97 % und eine Bounce-Rate ab 2 % sind hervorgehoben. Sie können nach Name oder ID suchen.
  • Zeilenaktionen: einen Test senden, den API-Befehl anzeigen und über das Menü die Benachrichtigung bearbeiten, ihre Vorlage in der Vorschau ansehen, die ID kopieren, ihre Nachrichten in den Protokollen öffnen oder sie löschen.

Ein Klick auf eine Zeile öffnet die Detailansicht der Benachrichtigung, die einen eigenen Link zum Teilen hat. Sie zeigt dieselben Statistiken für diese Benachrichtigung, verknüpft mit den passenden Nachrichten in den Protokollen. Dazu kommen die Sendungen pro Tag, die letzten Sendungen (alle 30 Sekunden aktualisiert), eine Vorschau der Vorlage, ihre Tracking- und UTM-Einstellungen, der Standardabsender und der API-Aufruf in cURL, TypeScript und Python. K und J springen zur vorherigen oder nächsten Benachrichtigung.

Bei einem SMTP-Anbieter gibt es keine Zustell- und Bounce-Raten, da SMTP keine Zustellereignisse meldet. Für die Statistiken ist das Leserecht für den Nachrichtenverlauf nötig.

API-Endpunkt

Senden Sie eine Transaktions-E-Mail mit einer POST-Anfrage:

Anfrage

curl -X POST \
  "https://v3.notifuse.com/api/transactional.send" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
  "workspace_id": "your_workspace",
  "notification": {
    "id": "password_reset",
    "external_id": "pwd-reset-user123-20240101",
    "channels": ["email"],
    "contact": {
      "email": "user@example.com"
    },
    "data": {
      "reset_token": "abc123",
      "expiry_time": "2024-01-01T12:00:00Z"
    },
    "metadata": {
      "user_id": "12345",
      "trigger": "forgot_password",
      "source": "web_app"
    },
    "email_options": {
      "from_name": "Support Team",
      "subject": "Reset your password, {{ contact.first_name }}",
      "reply_to": "support@yourcompany.com",
      "cc": ["admin@yourcompany.com"],
      "bcc": ["logs@yourcompany.com"],
      "attachments": [
        {
          "filename": "reset-guide.pdf",
          "content": "JVBERi0xLjQKJeLjz9MKMy4uLg==",
          "content_type": "application/pdf"
        }
      ]
    }
  }
}'

Parameter

ParameterTypPflichtBeschreibung
workspace_idstringJaKennung Ihres Arbeitsbereichs
notification.idstringJaKennung der Vorlage für die E-Mail
notification.external_idstringNeinEindeutige Kennung zur Deduplizierung
notification.channelsarrayJaMuss “email” enthalten
notification.contactobjectJaKontaktobjekt mit mindestens einem Feld email
notification.dataobjectNeinVorlagenvariablen für den E-Mail-Inhalt
notification.metadataobjectNeinTracking-Daten (in Vorlagen nicht verfügbar)
notification.email_optionsobjectNeinEinstellungen für das E-Mail-Routing

E-Mail-Optionen

ParameterTypBeschreibung
sender_idstringSendet von diesem Absender der Integration für Transaktions-E-Mails statt vom Absender der Vorlage. Eine unbekannte ID wird mit 400 abgelehnt, bevor der Kontakt angelegt oder aktualisiert wird
from_namestringÜberschreibt den Standard-Anzeigenamen des Absenders
subjectstringÜberschreibt die Betreffzeile der Vorlage (unterstützt Liquid, max. 255)
reply_tostringLegt eine eigene Antwortadresse fest, anstelle der Antwortadresse der Vorlage
ccarrayListe der Empfänger in Kopie
bccarrayListe der Empfänger in Blindkopie
attachmentsarrayDateianhänge (max. 20 Dateien, 3 MB pro Datei, 10 MB insgesamt)

Data und Metadata

Vorlagenvariablen (data)

Das Objekt data enthält die Variablen, die Ihre E-Mail-Vorlagen verwenden können:

{
  "data": {
    "order_id": "ORD-12345",
    "total": "$99.99",
    "discount_code": "WELCOME20"
  }
}

In Vorlagen stehen sie dann als {{ order_id }}, {{ total }}, {{ discount_code }} zur Verfügung.

Tracking-Daten (metadata)

Das Objekt metadata speichert Informationen für Analysen und Tracking und ist in Vorlagen nicht verfügbar:

{
  "metadata": {
    "campaign_id": "welcome-series",
    "source": "mobile_app",
    "user_segment": "premium"
  }
}

Verwenden Sie Metadaten für internes Tracking, Analysen und Reporting.

E-Mail-Anhänge

Hängen Sie Rechnungen, Belege, Tickets oder andere Dokumente an Ihre Transaktions-E-Mails an. Anhänge werden im Speicher automatisch dedupliziert.

Grenzen für Anhänge

  • Maximale Anzahl: 20 Anhänge pro E-Mail
  • Dateigröße: 3 MB pro Datei
  • Gesamtgröße: 10 MB pro E-Mail
  • Unterstützte Formate: alle Dateitypen (PDF, PNG, JPEG, DOCX usw.)

Parameter für Anhänge

ParameterTypPflichtBeschreibung
filenamestringJaDateiname (max. 255 Zeichen)
contentstringJaBase64-kodierter Dateiinhalt
content_typestringNeinMIME-Typ (z. B. “application/pdf”), wird automatisch erkannt, wenn er fehlt
dispositionstringNein“attachment” (Standard) oder “inline”
content_idstringNeinContent-ID für Inline-Anhänge, im HTML-Inhalt als <img src="cid:..."> referenziert. Nur erlaubt, wenn disposition “inline” ist. Fehlt sie, gilt der Dateiname.

Beispiel mit PDF-Rechnung

{
  "workspace_id": "your_workspace",
  "notification": {
    "id": "order_confirmation",
    "contact": {
      "email": "customer@example.com"
    },
    "data": {
      "order_id": "ORD-12345",
      "total": "$99.99"
    },
    "email_options": {
      "attachments": [
        {
          "filename": "invoice-12345.pdf",
          "content": "JVBERi0xLjQKJeLjz9MKMy4uLg==",
          "content_type": "application/pdf",
          "disposition": "attachment"
        }
      ]
    }
  }
}

Beispiel mit mehreren Anhängen

{
  "email_options": {
    "attachments": [
      {
        "filename": "invoice.pdf",
        "content": "JVBERi0xLjQKJeLjz9MK...",
        "content_type": "application/pdf"
      },
      {
        "filename": "receipt.png",
        "content": "iVBORw0KGgoAAAANSUhEU...",
        "content_type": "image/png"
      },
      {
        "filename": "terms.docx",
        "content": "UEsDBBQABgAIAAAAIQ...",
        "content_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
      }
    ]
  }
}

Inline-Bilder (Content-ID)

Betten Sie Bilder pro Empfänger, etwa QR-Codes oder personalisierte Grafiken, direkt in den E-Mail-Inhalt ein, statt sie unter einer URL zu hosten. Setzen Sie disposition auf "inline", geben Sie dem Anhang eine content_id und referenzieren Sie ihn im HTML Ihrer Vorlage als <img src="cid:...">:

{
  "email_options": {
    "attachments": [
      {
        "filename": "check-in-qr.png",
        "content": "iVBORw0KGgoAAAANSUhEU...",
        "content_type": "image/png",
        "disposition": "inline",
        "content_id": "checkInQr"
      }
    ]
  }
}

Und in der E-Mail-Vorlage:

<img src="cid:checkInQr" alt="Your check-in QR code" />

Hinweise:

  • content_id darf nur Buchstaben, Ziffern und die Zeichen . _ - @ enthalten (max. 255 Zeichen) und wird nur akzeptiert, wenn disposition "inline" ist.
  • Fehlt content_id, dient der Dateiname als Content-ID, sodass auch <img src="cid:check-in-qr.png"> funktioniert.
  • Inline-Bilder werden in einem MIME-Teil multipart/related neben dem HTML-Inhalt zugestellt, sodass E-Mail-Programme sie im Inhalt anzeigen und nicht als herunterladbare Anhänge.
  • Da das Bild im Nachrichteninhalt mitreist, rufen Link-Proxys und Bild-Caching-Dienste es nie ab und protokollieren es auch nicht. Das passt zu empfängerspezifischen Geheimnissen wie QR-Codes.
  • Bei Mailgun wird die content_id auch zum Dateinamen des zugestellten Teils. Wählen Sie beim Versand über Mailgun daher eine content_id mit Dateiendung (z. B. checkInQr.png).

Häufige Anwendungsfälle

  • Bestellbestätigungen: Rechnungen und Belege anhängen
  • Buchungsbestätigungen: Tickets und Reisepläne anhängen
  • Rechtsdokumente: Verträge und Vereinbarungen anhängen
  • Berichte: Analyseberichte und Zusammenfassungen anhängen
  • Zertifikate: Abschlusszertifikate und Badges anhängen
  • Veranstaltungstickets: QR-Codes pro Empfänger als Inline-Bilder einbetten

SMTP-Bridge

Notifuse hat einen eingebauten SMTP-Bridge-Server, sodass Sie Transaktions-E-Mails aus gewöhnlichen SMTP-Clients senden können, statt die HTTP-API aufzurufen. Er eignet sich für:

  • Altsysteme: Anbindung bestehender Anwendungen, die nur SMTP unterstützen
  • E-Mail-Bibliotheken: Nutzung gängiger E-Mail-Bibliotheken in jeder Programmiersprache
  • Framework-Integration: Arbeit mit Frameworks, die SMTP von Haus aus unterstützen
  • Schrittweise Migration: Wechsel von bestehenden E-Mail-Anbietern, ohne den Anwendungscode zu ändern

So funktioniert es

Der SMTP-Bridge-Server nimmt E-Mails auf Port 587 (STARTTLS) oder 465 (implizites TLS) an. Der Inhalt der E-Mail muss eine JSON-Nutzlast im Format der Transaktions-API enthalten, und Sie authentifizieren sich mit den API-Zugangsdaten Ihres Arbeitsbereichs.

E-Mails über SMTP senden

Authentifizierung

  • Benutzername: die API-E-Mail-Adresse Ihres Arbeitsbereichs (die E-Mail-Adresse, die zu Ihrem API-Schlüssel gehört)
  • Passwort: der API-Schlüssel Ihres Arbeitsbereichs
  • Sicherheit: STARTTLS (Port 587) oder implizites TLS / SMTPS (Port 465), je nach Ihrer Einstellung SMTP_BRIDGE_TLS
  • Server: der Host Ihrer konfigurierten SMTP-Bridge (z. B. smtp.yourdomain.com)

E-Mail-Format

Der Inhalt der E-Mail muss eine JSON-Nutzlast im Format der Transaktions-API sein:

{
  "workspace_id": "your_workspace",
  "notification": {
    "id": "password_reset",
    "external_id": "unique-id-123",
    "channels": ["email"],
    "contact": {
      "email": "user@example.com",
      "first_name": "John",
      "last_name": "Doe"
    },
    "data": {
      "reset_token": "abc123",
      "expiry_time": "1 hour"
    }
  }
}

Berechtigungen

Das Schreibrecht für Transaktional reicht allein zum Senden aus, über die API wie über die SMTP-Bridge. Ein API-Schlüssel nur zum Senden ist deshalb praktikabel: Geben Sie einem Schlüssel das Schreibrecht für Transaktional und sonst nichts, dann kann er E-Mails senden, ohne einen einzigen Kontakt zu lesen oder zu bearbeiten. Siehe Admins & API-Schlüssel.

Für einen so eng gefassten Schlüssel gelten zwei Einschränkungen, auf der SMTP-Bridge wie in der API:

  • Ohne Schreibrecht für Kontakte legt ein Versand den Kontakt des Empfängers zwar an, wenn er noch nicht existiert, speichert aber nur seine E-Mail-Adresse. Alle anderen Felder des Objekts contact werden verworfen, und ein bestehender Kontakt wird nie geändert.
  • Ohne Leserecht für Kontakte wird ein Versand mit cc oder bcc abgelehnt. Auf der SMTP-Bridge stammen cc und bcc aus den Headern Cc: und Bcc: der Nachricht, sodass ein reiner Sende-Zugang, der sie setzt, schon bei der Übergabe der Nachricht abgewiesen wird.

Geben Sie dem Schlüssel Lese- und Schreibrecht für Kontakte, wenn er beim Senden Kontaktprofile anreichern oder zusätzliche Empfänger in Kopie setzen soll. Mit beiden Rechten verhält sich der Schlüssel wie bisher.

Das Schreibrecht für Transaktional deckt jeden Weg ab, auf dem über die Zugangsdaten Ihres Anbieters echte E-Mails verschickt werden: /api/transactional.send, /api/transactional.testTemplate und die SMTP-Bridge. Das Testen eines E-Mail-Anbieters (/api/email.testProvider) ist dem Inhaber des Arbeitsbereichs vorbehalten, ein API-Schlüssel kann es also nicht aufrufen. Eine Test-E-Mail braucht außerdem das Leserecht für Vorlagen und, wenn sie für eine Verteilerliste verschickt wird (list_id), das Leserecht für Listen.

Das Recht Gelesen für Transaktional deckt nur die Definitionen der Benachrichtigungen ab (sie auflisten und eine öffnen). Senden kann ein Schlüssel damit nicht.

Vorlagenintegration

Datenstruktur in Vorlagen

Ihre Vorlagen können sowohl die API-Daten als auch das Kontaktprofil verwenden:

<!-- From API data -->
Hello! Your order #{{ order_id }} has been confirmed.

<!-- From contact profile (automatically enriched) -->
Dear {{ contact.first_name }} {{ contact.last_name }},

<!-- Combining both -->
We've sent your order #{{ order_id }} to {{ contact.email }}.

Bedingte Blöcke

Blöcke einer visuellen Vorlage lassen sich nur dann verschicken, wenn eine Bedingung auf diese Daten zutrifft, etwa ein Abschnitt, der nur erscheint, wenn order.total größer als 100 ist. Siehe Bedingte Blöcke.

Vollständiges Beispiel

API-Anfrage:

{
  "workspace_id": "your_workspace",
  "notification": {
    "id": "order_confirmation",
    "external_id": "order-12345-confirmation",
    "contact": {
      "email": "sarah@example.com"
    },
    "data": {
      "order_id": "ORD-12345",
      "total": "$99.99",
      "items": ["Product A", "Product B"]
    },
    "metadata": {
      "campaign_id": "order-confirmations",
      "source": "checkout"
    }
  }
}

Bestehendes Kontaktprofil:

{
  "first_name": "Sarah",
  "last_name": "Johnson",
  "email": "sarah@example.com",
  "phone": "+1234567890"
}

In der Vorlage verfügbar:

Hi {{ contact.first_name }}!

Your order #{{ order_id }} totaling {{ total }} has been confirmed.

Items:
{% for item in items %}
- {{ item }}
{% endfor %}

We'll send updates to {{ contact.email }}.

API-Referenz

Beispiele für die Deduplizierung

Bestellbestätigungen

{
  "external_id": "order-12345-confirmation"
}

Passwort-Zurücksetzungen

{
  "external_id": "pwd-reset-user123-20240101"
}

Willkommens-E-Mails

{
  "external_id": "welcome-user123"
}

Einheitliche Muster für external_id verhindern doppelte Benachrichtigungen, auch wenn Ihre Anwendung mehrere Anfragen sendet.

Die vollständige API-Dokumentation und weitere Parameter finden Sie in der API-Referenz.