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
contactin 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 untercontactbereit.
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:
- Legt den Kontakt an oder aktualisiert ihn und sucht ihn dann anhand der E-Mail-Adresse in Ihrem Arbeitsbereich
- Legt die Schlüssel von
dataauf die oberste Ebene der Vorlagenvariablen und das gespeicherte Profil des Kontakts untercontact - Rendert die Vorlage mit den vollständigen Kontaktdaten
- 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 derselbenexternal_idgehen 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
| Parameter | Typ | Pflicht | Beschreibung |
|---|---|---|---|
workspace_id | string | Ja | Kennung Ihres Arbeitsbereichs |
notification.id | string | Ja | Kennung der Vorlage für die E-Mail |
notification.external_id | string | Nein | Eindeutige Kennung zur Deduplizierung |
notification.channels | array | Ja | Muss “email” enthalten |
notification.contact | object | Ja | Kontaktobjekt mit mindestens einem Feld email |
notification.data | object | Nein | Vorlagenvariablen für den E-Mail-Inhalt |
notification.metadata | object | Nein | Tracking-Daten (in Vorlagen nicht verfügbar) |
notification.email_options | object | Nein | Einstellungen für das E-Mail-Routing |
E-Mail-Optionen
| Parameter | Typ | Beschreibung |
|---|---|---|
sender_id | string | Sendet 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_name | string | Überschreibt den Standard-Anzeigenamen des Absenders |
subject | string | Überschreibt die Betreffzeile der Vorlage (unterstützt Liquid, max. 255) |
reply_to | string | Legt eine eigene Antwortadresse fest, anstelle der Antwortadresse der Vorlage |
cc | array | Liste der Empfänger in Kopie |
bcc | array | Liste der Empfänger in Blindkopie |
attachments | array | Dateianhä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
| Parameter | Typ | Pflicht | Beschreibung |
|---|---|---|---|
filename | string | Ja | Dateiname (max. 255 Zeichen) |
content | string | Ja | Base64-kodierter Dateiinhalt |
content_type | string | Nein | MIME-Typ (z. B. “application/pdf”), wird automatisch erkannt, wenn er fehlt |
disposition | string | Nein | “attachment” (Standard) oder “inline” |
content_id | string | Nein | Content-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_iddarf nur Buchstaben, Ziffern und die Zeichen._-@enthalten (max. 255 Zeichen) und wird nur akzeptiert, wenndisposition"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/relatedneben 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_idauch zum Dateinamen des zugestellten Teils. Wählen Sie beim Versand über Mailgun daher einecontent_idmit 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
contactwerden verworfen, und ein bestehender Kontakt wird nie geändert. - Ohne Leserecht für Kontakte wird ein Versand mit
ccoderbccabgelehnt. Auf der SMTP-Bridge stammenccundbccaus den HeadernCc:undBcc: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.
