Externe notificaties
Registreer e-mails die je eigen systeem naar een klant stuurde, zodat medewerkers ze in Tillor terugzien
Verstuurt jouw systeem zelf e-mails naar klanten (nieuwsbrief, boekingsbevestiging, herinnering)? Registreer ze dan in Tillor. Medewerkers zien ze bij de klant, op de factuur en in het overzicht Notificaties, naast de notificaties die Tillor zelf verstuurt.
Tillor verstuurt niets: je registreert een bericht dat al verzonden is. Externe notificaties dragen in de app altijd het label Extern met jouw bronnaam, zodat ze nooit voor een Tillor-notificatie doorgaan.
Toegang
De gebruiker achter de API-sleutel heeft in de organisatie een van deze permissies nodig. Een beheerder kent ze toe bij de gebruikerspermissies van de organisatie, in de groep Notificaties (Externe notificaties registreren en Externe notificaties van anderen beheren).
| Permissie | Wat mag je |
|---|---|
notifications:external:write | Notificaties registreren en je eigen registraties bijwerken of verwijderen |
notifications:external:manage-others | Ook registraties van andere gebruikers of integraties bijwerken of verwijderen |
Eén gebruiker per integratie
Eigenaarschap hangt aan de gebruiker van de API-sleutel. Gebruik per integratie een eigen (service)gebruiker, dan kan de ene integratie nooit de notificaties van de andere wijzigen.
Endpoints
Alle paden staan onder /api/orgs/:orgId. Exacte schema's: OpenAPI, tag notifications.
| Method | Pad | Beschrijving |
|---|---|---|
| POST | /notifications/external | Notificatie registreren |
| PATCH | /notifications/external/{id} | Status, tijdstippen of inhoud bijwerken |
| DELETE | /notifications/external/{id} | Definitief verwijderen |
| GET | /notifications?source=EXTERNAL | Geregistreerde notificaties oplijsten (filter ook op externalSource, externalReference, customerId, invoiceId) |
| GET | /notifications/{id} | Eén notificatie ophalen |
Notificaties die Tillor zelf verstuurde kun je via deze endpoints niet wijzigen of verwijderen; ze geven 404.
Registreren
curl -X POST "https://tillor.eu/api/orgs/org_abc123/notifications/external" \
-H "x-api-key: tkn_xxx" \
-H "X-Tillor-Org-Id: org_abc123" \
-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 velden en limieten staan in OpenAPI. Deze velden hebben regels die je vooraf moet kennen:
| Veld | Regel |
|---|---|
externalSource | Naam van jouw systeem in kleine letters, cijfers, ., _ of - (bv. mailchimp). Medewerkers zien deze naam bij de notificatie |
externalReference | Jouw eigen ID voor dit bericht, uniek binnen externalSource |
name | Kort label voor medewerkers (bv. "Boekingsbevestiging"). Hierop kan gezocht worden |
customerId / invoiceId | Minstens één van beide. Bepaalt waar de notificatie verschijnt. Stuur je alleen invoiceId, dan koppelt Tillor ook de klant van die factuur. Een onbekend ID, of een factuur van een andere klant, geeft 400 |
status | SENT, FAILED, BOUNCED of COMPLAINED. Zonder sentAt bij SENT gebruikt Tillor het moment van registratie |
sentAt, readAt, clickedAt | ISO 8601 met tijdzone, bv. 2026-09-19T08:15:00Z. Andere waarden worden geweigerd |
email.attachments | Alleen metadata (filename, contentType, size). Bestanden zelf worden niet opgeslagen |
Veilig opnieuw proberen
POST is idempotent op externalSource + externalReference. Stuur je dezelfde combinatie opnieuw (bijvoorbeeld na een time-out), dan krijg je de bestaande notificatie terug en wordt er niets gewijzigd. Wil je iets aanpassen, gebruik dan PATCH.
Geen persoonsgegevens in externalReference of name
externalSource, externalReference en name worden onversleuteld opgeslagen omdat erop gezocht wordt. Gebruik een technisch ID, geen e-mailadres of naam. Een externalReference met @ wordt geweigerd. Ontvanger, onderwerp, inhoud en bijlagen worden wél versleuteld opgeslagen.
Bijwerken en verwijderen
Stuur bij PATCH alleen de velden die wijzigen, bijvoorbeeld wanneer een e-mail achteraf bouncet:
curl -X PATCH "https://tillor.eu/api/orgs/org_abc123/notifications/external/NOTIFICATION_ID" \
-H "x-api-key: tkn_xxx" \
-H "X-Tillor-Org-Id: org_abc123" \
-H "Content-Type: application/json" \
-d '{ "status": "BOUNCED", "errorMessage": "Mailbox bestaat niet" }'DELETE verwijdert de notificatie definitief, inclusief inhoud. Gebruik dit ook om aan een verwijderverzoek (AVG) te voldoen.
Een PATCH die niets verandert doet niets: geen wijziging, geen event. Wijzig je de inhoud (label, ontvanger, afzender, onderwerp, tekst, HTML of bijlagen) of verwijder je een notificatie, dan staat dat in de activiteitenlog van de klant of factuur, met de gebruiker die het deed. Updates van status, readAt of clickedAt komen daar niet in, zodat je opens en kliks kunt blijven synchroniseren.
HTML en privacy
Tillor toont de HTML aan medewerkers zoals de klant ze ontving, maar behandelt ze als niet-vertrouwde inhoud:
- Bij het opslaan worden scripts, formulieren, iframes, embeds en event-attributen (
onclick, ...) verwijderd. Links openen in een nieuw tabblad - De voorvertoning draait in een afgeschermd frame zonder scripts en zonder toegang tot de Tillor-sessie
- Externe afbeeldingen en lettertypes laden niet automatisch, zodat het openen van een notificatie geen trackingpixel activeert. De medewerker kan afbeeldingen per notificatie inladen
Reken er dus niet op dat "geopend"-tracking in jouw systeem afgaat wanneer een medewerker de notificatie bekijkt.
Wat Tillor niet doet met externe notificaties
- Niet (opnieuw) versturen of automatisch herproberen
- Geen statusupdates ophalen bij jouw mailprovider: jij houdt de status actueel met
PATCH - Niet meetellen in de lijsten Mislukte notificaties, Bounced notificaties en Lopende notificaties of in de tellers bovenaan het notificatieoverzicht, omdat Tillor jouw status niet kan verifiëren. Ze staan wel onder Recente communicaties
Webhooks en SSE
| Event | Wanneer |
|---|---|
notification-delivery:updated | Bij registreren en bij elke PATCH die iets wijzigt. Bevat de volledige notificatie |
notification-delivery:deleted | Bij DELETE. Bevat alleen id, source, externalSource, externalReference, customerId en invoiceId |
Het veld source is EXTERNAL voor jouw registraties en INTERNAL voor notificaties van Tillor. Filter daarop als je je eigen events wilt overslaan. Zie Webhooks en SSE.