E-Mail-Zustellstatus einrichten | Output.Rocks Documentation

Output.Rocks kann Rückmeldungen eines Mailproviders automatisch als delivered oder bounced übernehmen. Unterstützt werden Amazon SES über Amazon SNS und Mailjet. Ohne Provider-Callback entscheiden Sie den Zustellstatus manuell.

Aktivieren Sie zuerst in der verwendeten E-Mail-Vorlage das Bounce-Handling. Nach dem Versand bleibt der E-Mail-Prozess dann in waiting_for_delivery, bis ein Callback oder eine manuelle Aktion den Ausgang festlegt.

Überblick

Weg	Automatische Rückmeldungen	Output.Rocks-Endpunkt
Amazon SES/SNS	`Delivery`, `Bounce`, `Complaint`	`POST /api/sns-notification`
Mailjet	`sent`, `bounce`, `blocked`, `spam`	`POST /api/mailjet-notification`
Anderer SMTP-Provider	keine	Status manuell pflegen oder E-Mail erneut senden

Output.Rocks ordnet die Ereignisse so zu:

Provider-Ereignis	Zustellergebnis in Output.Rocks
SES `Delivery`	`delivered`
SES `Bounce`	`bounced`
SES `Complaint`	`bounced` mit Ereignistyp `complaint`
Mailjet `sent`	`delivered`
Mailjet `bounce`, `blocked` oder `spam`	`bounced`

Voraussetzungen

Aktivieren Sie Bounce-Handling in jeder E-Mail-Vorlage, deren Zustellung verfolgt werden soll.
Erstellen Sie unter Integration → API-Token ein eigenes Token für den Callback.
Stellen Sie einen öffentlich erreichbaren HTTPS-Endpunkt Ihrer Output.Rocks-Instanz bereit.
Konfigurieren Sie den Callback beim Provider und senden Sie anschließend eine Test-E-Mail.

Token und Mandantenbezug

Ein API-Token gehört immer zu einem Client und kann zusätzlich einem Umgebungs-Mandanten zugewiesen sein. Eingehende Benachrichtigungen übernehmen diesen Bezug. Der E-Mail-Prozess wird innerhalb des Clients anhand der Provider-Message-ID gefunden; der Umgebungs-Mandant ist dabei kein zusätzliches Zuordnungskriterium.

Verwenden Sie deshalb für jeden Callback und fachlichen Scope ein passendes Client- oder Umgebungs-Mandanten-Token. Teilen Sie weder Topics noch Callback-Tokens zwischen verschiedenen Clients.

Die Token-Erstellung, Rotation und Deaktivierung liegt in Ihrer Verantwortung. Verwenden Sie in Anleitungen, Tickets und Screenshots niemals einen echten Token-Wert. Die Beispiele auf dieser Seite enthalten ausschließlich Platzhalter.

Die Integration unterstützt ausdrücklich kundeneigene SES- und SNS-Ressourcen. Output.Rocks benötigt dafür keine AWS-Zugangsdaten; SNS sendet die Ereignisse an den HTTPS-Endpunkt.

Erstellen Sie in Ihrem AWS-Konto ein SNS-Topic in der Region der verwendeten SES-Identität.
Erlauben Sie Amazon SES in der Topic-Policy, Nachrichten an das Topic zu veröffentlichen.
Verwenden Sie ein eigenes Topic pro Callback-Scope und Umgebung, damit Token und Zustellereignisse eindeutig getrennt bleiben.

2. SES-Ereignisse verbinden

Hinterlegen Sie das SNS-Topic in Amazon SES als Ziel für Delivery, Bounce und Complaint. Je nach Versandkonfiguration erfolgt dies an der verifizierten SES-Identität oder über das verwendete Configuration Set.

Binden Sie alle drei Ereignisse ein. Ohne Delivery bleibt eine erfolgreiche Zustellung offen; ohne Bounce oder Complaint werden problematische Empfänger nicht erkannt.

3. HTTPS-Subscription anlegen

Legen Sie am SNS-Topic eine Subscription mit Protokoll HTTPS und diesem Endpunkt an:

https://<instanz>/api/sns-notification?auth-token=<token>

Lassen Sie Raw message delivery für die Subscription deaktiviert. Output.Rocks erwartet den normalen SNS-JSON-Envelope mit Type, MessageId und Message; die Bestätigung enthält zusätzlich die SubscribeURL. Bei aktivierter Raw Delivery fehlt dieser Envelope, der direkte SES-Payload wird verworfen und wegen der Antwort 200 OK von SNS nicht erneut zugestellt.

SNS kann für diesen Callback keinen eigenen Authentifizierungs-Header setzen. Deshalb steht das Output.Rocks-API-Token als auth-token in der Query-URL. Übertragen Sie die URL ausschließlich per HTTPS und schützen Sie sie wie ein Passwort, insbesondere in Logs, Browser-Verläufen und Infrastruktur-State.

4. Automatische Bestätigung prüfen

SNS sendet zunächst eine SubscriptionConfirmation mit einer SubscribeURL. Output.Rocks ruft diese URL automatisch auf; eine manuelle Bestätigung ist bei gültigem Token und erreichbarem Endpunkt nicht nötig. Prüfen Sie anschließend in SNS, ob die Subscription als Confirmed angezeigt wird.

5. Zustellung testen

Senden Sie eine Test-E-Mail über die konfigurierte SES-Identität und, falls verwendet, das richtige Configuration Set. Öffnen Sie danach den E-Mail-Prozess in Output.Rocks und prüfen Sie die Zustellhistorie.

Mailjet einrichten

Öffnen Sie in Mailjet die Event-Webhook-Konfiguration.
Hinterlegen Sie diesen HTTPS-Endpunkt:

https://<instanz>/api/mailjet-notification?auth-token=<token>

Aktivieren Sie die Ereignisse sent, bounce, blocked und spam.
Senden Sie eine Test-E-Mail und prüfen Sie den zugehörigen E-Mail-Prozess in Output.Rocks.

Mailjet kann mehrere Ereignisse als JSON-Array in einem Request senden. Jedes Ereignis muss sowohl MessageID als auch Message_GUID enthalten. Output.Rocks verwendet Message_GUID, um doppelte Ereignisse zu erkennen, und MessageID, um den E-Mail-Prozess zuzuordnen.

Ohne Provider-Callback

Bei einem SMTP-Provider ohne Callback bleibt ein Prozess mit aktiviertem Bounce-Handling ohne Timeout in waiting_for_delivery. Output.Rocks nimmt keine automatische Entscheidung vor.

Filtern Sie die E-Mail-Prozesse regelmäßig nach Zustellergebnis → Ausstehend und wählen Sie eine passende Aktion:

Als zugestellt markieren führt den Prozess als delivered fort.
Als nicht zugestellt markieren führt ihn als bounced fort.
Erneut senden startet den manuellen Neuversand.

Die Zustellentscheidung ist in der E-Mail-Prozessliste, im Prozess-Leitstand und über Batch-Aktionen möglich. Nach einer manuellen Entscheidung werden die für delivered oder bounced konfigurierten Zustellstatus-Webhooks ausgeführt.

Ausstehend ist ein abgeleiteter Filter für Prozesse mit Sendestatus sent oder resend, zu denen noch keine Provider-Benachrichtigung vorliegt. pending ist kein eigener Backend-Sendestatus.

Zustellhistorie prüfen

Öffnen Sie die Detailansicht eines E-Mail-Prozesses. Unter Zustellhistorie sehen Sie Provider, Ereignistyp, Zeitpunkt und eine Zusammenfassung der Rückmeldung. Provider-Antwort anzeigen blendet die technischen Rohdaten des Ereignisses ein.

Für die gezielte Suche stehen unter Zustellergebnis die Filter Ausstehend, Zugestellt, Zurückgewiesen (inkl. Complaints), Complaint und Rückläufer bearbeitet zur Verfügung. Der separate Sendestatus zeigt die gespeicherten Werte wie sent, delivered, bounced, bounce_handled oder resend.

Beschwerden und Suppression

Eine Beschwerde (Complaint bei SES beziehungsweise spam bei Mailjet) wird in Output.Rocks wie ein Bounce behandelt. Schreiben Sie den betroffenen Empfänger nicht erneut an. Prüfen Sie zusätzlich in Ihrem Provider-Konto die Suppression- oder Sperrlisten und klären Sie die weitere Behandlung nach Ihren eigenen Compliance-Vorgaben.

Fehlerbehebung

Symptom	Ursache und Lösung
Callback antwortet mit `401 Unauthorized`	Das Token ist falsch, noch nicht aktiv oder deaktiviert. Erstellen bzw. aktivieren Sie ein passendes Token und aktualisieren Sie die Callback-URL.
SNS-Subscription bleibt `Pending confirmation`	Prüfen Sie HTTPS-Erreichbarkeit und Token. Output.Rocks bestätigt die Subscription nur, wenn die `SubscriptionConfirmation` authentifiziert ankommt.
SNS meldet erfolgreiche Zustellung, aber die Zustellhistorie bleibt leer	Prüfen Sie an der HTTPS-Subscription, ob Raw message delivery deaktiviert ist. Nur der normale SNS-Envelope kann verarbeitet werden.
Ereignis erscheint, aber kein E-Mail-Prozess ändert sich	Prüfen Sie Client-Scope und Provider-Message-ID. Die Zuordnung erfolgt nur über Client und Message-ID, nicht zusätzlich über den Umgebungs-Mandanten.
Mailjet-Ereignis wird ignoriert	Prüfen Sie, ob `MessageID` und `Message_GUID` im Event vorhanden sind. `Message_GUID` dient der Deduplizierung, `MessageID` der Prozesszuordnung.
Prozess bleibt in `waiting_for_delivery`	Der Provider hat keinen verwertbaren Callback geliefert. Beheben Sie den Callback oder entscheiden bzw. versenden Sie den Prozess manuell erneut; es gibt keinen automatischen Timeout.
Ereignis ist doppelt	Output.Rocks ignoriert bereits verarbeitete Provider-Ereignisse innerhalb desselben Clients.

Verhalten bei fehlgeschlagenen Provider-Aufrufen

Amazon SNS: Ein 401 ist ein permanenter 4xx-Fehler und wird nicht erneut zugestellt. SNS wiederholt standardmäßig nur 429- und 5xx-Antworten gemäß der Delivery Policy.
Mailjet: Mailjet erwartet 200 OK und wiederholt andere Antworten laut Event-API alle 30 Sekunden für bis zu 24 Stunden; ein neues Ereignis kann diese Wiederholungsserie beenden.

Rotieren Sie ein Token kontrolliert: neues Token erstellen, Callback-URL beziehungsweise SNS-Subscription umstellen, einen Test-Callback prüfen und erst danach das alte Token deaktivieren.