Externe Benachrichtigungen
Registrieren Sie E-Mails, die Ihr eigenes System an einen Kunden gesendet hat, damit Mitarbeitende sie in Tillor wiederfinden
Zuletzt aktualisiert am
Versendet Ihr System selbst E-Mails an Kunden (Newsletter, Buchungsbestätigung, Erinnerung)? Registrieren Sie sie dann in Tillor. Mitarbeitende sehen sie beim Kunden, auf der Rechnung und in der Übersicht Benachrichtigungen, neben den Benachrichtigungen, die Tillor selbst versendet.
Tillor versendet nichts: Sie registrieren eine Nachricht, die bereits gesendet wurde. Externe Benachrichtigungen tragen in der App immer das Label Extern mit Ihrem Quellennamen, sodass sie nie für eine Tillor-Benachrichtigung gehalten werden.
Zugriff
Der Benutzer hinter dem API-Schlüssel benötigt in der Organisation eine dieser Berechtigungen. Ein Administrator vergibt sie bei den Benutzerberechtigungen der Organisation, in der Gruppe Benachrichtigungen (Externe Benachrichtigungen registrieren und Externe Benachrichtigungen anderer verwalten).
| Berechtigung | Was Sie dürfen |
|---|---|
notifications:external:write | Benachrichtigungen registrieren und Ihre eigenen Registrierungen aktualisieren oder löschen |
notifications:external:manage-others | Auch Registrierungen anderer Benutzer oder Integrationen aktualisieren oder löschen |
Ein Benutzer pro Integration
Die Eigentümerschaft hängt am Benutzer des API-Schlüssels. Verwenden Sie pro Integration einen eigenen (Service-)Benutzer, dann kann eine Integration nie die Benachrichtigungen einer anderen ändern.
Endpunkte
Alle Pfade stehen unter /api/orgs/:orgId. Genaue Schemas: OpenAPI, Tag notifications.
| Methode | Pfad | Beschreibung |
|---|---|---|
| POST | /notifications/external | Benachrichtigung registrieren |
| PATCH | /notifications/external/{id} | Status, Zeitpunkte oder Inhalt aktualisieren |
| DELETE | /notifications/external/{id} | Endgültig löschen |
| GET | /notifications?source=EXTERNAL | Registrierte Benachrichtigungen auflisten (filtern Sie auch nach externalSource, externalReference, customerId, invoiceId) |
| GET | /notifications/{id} | Eine Benachrichtigung abrufen |
Benachrichtigungen, die Tillor selbst versendet hat, können Sie über diese Endpunkte nicht ändern oder löschen; sie ergeben 404.
Registrieren
curl -X POST "https://tillor.eu/api/orgs/org_abc123/notifications/external" \
-H "x-api-key: tkn_xxx" \
-H "Content-Type: application/json" \
-d '{
"externalSource": "mailchimp",
"externalReference": "campaign-42:member-9f3a",
"name": "Boekingsbevestiging",
"customerId": "clx789...",
"channel": "EMAIL",
"status": "SENT",
"sentAt": "2026-09-19T08:15:00Z",
"email": {
"to": "jan@voorbeeld.nl",
"from": "Recreatiepark Het Meer <info@recreatiepark-het-meer.be>",
"subject": "Je boeking is bevestigd",
"htmlBody": "<p>Dag Jan, ...</p>",
"attachments": [{ "filename": "bevestiging.pdf", "contentType": "application/pdf", "size": 48211 }]
}
}'Alle Felder und Grenzwerte stehen in OpenAPI. Für diese Felder gelten Regeln, die Sie vorab kennen sollten:
| Feld | Regel |
|---|---|
externalSource | Name Ihres Systems in Kleinbuchstaben, Ziffern, ., _ oder - (z. B. mailchimp). Mitarbeitende sehen diesen Namen bei der Benachrichtigung |
externalReference | Ihre eigene ID für diese Nachricht, eindeutig innerhalb von externalSource |
name | Kurzes Label für Mitarbeitende (z. B. „Boekingsbevestiging“). Danach kann gesucht werden |
customerId / invoiceId | Mindestens eines von beiden. Bestimmt, wo die Benachrichtigung erscheint. Senden Sie nur invoiceId, verknüpft Tillor auch den Kunden dieser Rechnung. Eine unbekannte ID oder eine Rechnung eines anderen Kunden ergibt 400 |
status | SENT, FAILED, BOUNCED oder COMPLAINED. Ohne sentAt bei SENT verwendet Tillor den Zeitpunkt der Registrierung |
sentAt, readAt, clickedAt | ISO 8601 mit Zeitzone, z. B. 2026-09-19T08:15:00Z. Andere Werte werden abgelehnt |
email.attachments | Nur Metadaten (filename, contentType, size). Die Dateien selbst werden nicht gespeichert |
Sicher erneut versuchen
POST ist idempotent auf externalSource + externalReference. Senden Sie dieselbe Kombination erneut (zum Beispiel nach einem Timeout), erhalten Sie die bestehende Benachrichtigung zurück, und es wird nichts geändert. Möchten Sie etwas anpassen, verwenden Sie PATCH.
Keine personenbezogenen Daten in externalReference oder name
externalSource, externalReference und name werden unverschlüsselt gespeichert, weil danach gesucht wird. Verwenden Sie eine technische ID, keine E-Mail-Adresse und keinen Namen. Eine externalReference mit @ wird abgelehnt. Empfänger, Betreff, Inhalt und Anhänge werden dagegen verschlüsselt gespeichert.
Aktualisieren und löschen
Senden Sie bei PATCH nur die Felder, die sich ändern, zum Beispiel wenn eine E-Mail nachträglich zurückgewiesen wird:
curl -X PATCH "https://tillor.eu/api/orgs/org_abc123/notifications/external/NOTIFICATION_ID" \
-H "x-api-key: tkn_xxx" \
-H "Content-Type: application/json" \
-d '{ "status": "BOUNCED", "errorMessage": "Mailbox bestaat niet" }'DELETE löscht die Benachrichtigung endgültig, einschließlich Inhalt. Nutzen Sie dies auch, um einer Löschanfrage (DSGVO) nachzukommen.
Ein PATCH, der nichts ändert, tut nichts: keine Änderung, kein Event. Ändern Sie den Inhalt (Label, Empfänger, Absender, Betreff, Text, HTML oder Anhänge) oder löschen Sie eine Benachrichtigung, steht das im Aktivitätsprotokoll des Kunden oder der Rechnung, mit dem Benutzer, der es getan hat. Aktualisierungen von Status, readAt oder clickedAt erscheinen dort nicht, damit Sie Öffnungen und Klicks weiter synchronisieren können.
HTML und Datenschutz
Tillor zeigt das HTML den Mitarbeitenden so, wie der Kunde es erhalten hat, behandelt es aber als nicht vertrauenswürdigen Inhalt:
- Beim Speichern werden Skripte, Formulare, iframes, Embeds und Event-Attribute (
onclick, ...) entfernt. Links öffnen sich in einem neuen Tab - Die Vorschau läuft in einem abgeschirmten Frame ohne Skripte und ohne Zugriff auf die Tillor-Sitzung
- Externe Bilder und Schriftarten werden nicht automatisch geladen, damit das Öffnen einer Benachrichtigung kein Tracking-Pixel auslöst. Der Mitarbeitende kann Bilder pro Benachrichtigung nachladen
Rechnen Sie also nicht damit, dass das „Geöffnet“-Tracking in Ihrem System anschlägt, wenn ein Mitarbeitender die Benachrichtigung ansieht.
Was Tillor mit externen Benachrichtigungen nicht tut
- Nicht (erneut) versenden oder automatisch erneut versuchen
- Keine Statusupdates bei Ihrem Mailanbieter abfragen: Sie halten den Status mit
PATCHaktuell - Nicht mitzählen in den Listen Fehlgeschlagene Benachrichtigungen, Zurückgewiesene Benachrichtigungen und Ausstehende Benachrichtigungen oder in den Zählern oben in der Benachrichtigungsübersicht, weil Tillor Ihren Status nicht verifizieren kann. Sie stehen aber unter Letzte Kommunikation
Webhooks und SSE
| Event | Wann |
|---|---|
notification-delivery:updated | Bei der Registrierung und bei jedem PATCH, der etwas ändert. Enthält die vollständige Benachrichtigung |
notification-delivery:deleted | Bei DELETE. Enthält nur id, source, externalSource, externalReference, customerId und invoiceId |
Das Feld source ist EXTERNAL für Ihre Registrierungen und INTERNAL für Benachrichtigungen von Tillor. Filtern Sie danach, wenn Sie Ihre eigenen Events überspringen möchten. Siehe Webhooks und SSE.