Notifiche esterne
Registra le e-mail che il tuo sistema ha inviato a un cliente, così il personale le ritrova in Tillor
Ultimo aggiornamento il
Il tuo sistema invia da sé e-mail ai clienti (newsletter, conferma di prenotazione, promemoria)? Registrale allora in Tillor. Il personale le vede nella scheda del cliente, sulla fattura e nel riepilogo Notifiche, accanto alle notifiche che Tillor invia in prima persona.
Tillor non invia nulla: registri un messaggio già spedito. Nell'app le notifiche esterne portano sempre l'etichetta Esterna con il nome della tua origine, così non passano mai per una notifica di Tillor.
Accesso
L'utente dietro la chiave API ha bisogno di uno di questi permessi nell'organizzazione. Un amministratore li assegna nei permessi utente dell'organizzazione, nel gruppo Notifiche (Registrare notifiche esterne e Gestire le notifiche esterne di altri).
| Permesso | Cosa puoi fare |
|---|---|
notifications:external:write | Registrare notifiche e aggiornare o eliminare le registrazioni proprie |
notifications:external:manage-others | Aggiornare o eliminare anche le registrazioni di altri utenti o integrazioni |
Un utente per integrazione
La proprietà dipende dall'utente della chiave API. Usa per ogni integrazione un utente (di servizio) proprio, così un'integrazione non potrà mai modificare le notifiche dell'altra.
Endpoint
Tutti i percorsi sono sotto /api/orgs/:orgId. Schemi esatti: OpenAPI, tag notifications.
| Method | Percorso | Descrizione |
|---|---|---|
| POST | /notifications/external | Registrare una notifica |
| PATCH | /notifications/external/{id} | Aggiornare stato, orari o contenuto |
| DELETE | /notifications/external/{id} | Eliminare definitivamente |
| GET | /notifications?source=EXTERNAL | Elencare le notifiche registrate (filtra anche per externalSource, externalReference, customerId, invoiceId) |
| GET | /notifications/{id} | Recuperare una notifica |
Le notifiche che Tillor ha inviato da sé non puoi modificarle né eliminarle tramite questi endpoint; danno 404.
Registrare
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 }]
}
}'Tutti i campi e i limiti sono in OpenAPI. Questi campi hanno regole che devi conoscere in anticipo:
| Campo | Regola |
|---|---|
externalSource | Nome del tuo sistema in minuscolo, cifre, ., _ o - (es. mailchimp). Il personale vede questo nome presso la notifica |
externalReference | Il tuo ID per questo messaggio, univoco all'interno di externalSource |
name | Breve etichetta per il personale (es. "Boekingsbevestiging"). Si può cercare per questo |
customerId / invoiceId | Almeno uno dei due. Determina dove compare la notifica. Se invii solo invoiceId, Tillor collega anche il cliente di quella fattura. Un ID sconosciuto, o una fattura di un altro cliente, dà 400 |
status | SENT, FAILED, BOUNCED o COMPLAINED. Senza sentAt con SENT Tillor usa il momento della registrazione |
sentAt, readAt, clickedAt | ISO 8601 con fuso orario, es. 2026-09-19T08:15:00Z. Altri valori vengono rifiutati |
email.attachments | Solo metadati (filename, contentType, size). I file in sé non vengono salvati |
Riprovare in sicurezza
POST è idempotente su externalSource + externalReference. Se invii di nuovo la stessa combinazione (ad esempio dopo un time-out), ottieni la notifica esistente e non viene modificato nulla. Se vuoi cambiare qualcosa, usa PATCH.
Nessun dato personale in externalReference o name
externalSource, externalReference e name vengono salvati non cifrati perché vi si può cercare. Usa un ID tecnico, non un indirizzo e-mail o un nome. Un externalReference con @ viene rifiutato. Destinatario, oggetto, contenuto e allegati vengono invece salvati cifrati.
Aggiornare ed eliminare
Con PATCH invia solo i campi che cambiano, ad esempio quando un'e-mail rimbalza in seguito:
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 elimina la notifica in modo definitivo, contenuto compreso. Usalo anche per soddisfare una richiesta di cancellazione (GDPR).
Un PATCH che non cambia nulla non fa nulla: nessuna modifica, nessun evento. Se modifichi il contenuto (etichetta, destinatario, mittente, oggetto, testo, HTML o allegati) o elimini una notifica, risulta nel registro attività del cliente o della fattura, con l'utente che l'ha fatto. Gli aggiornamenti di stato, readAt o clickedAt non vi compaiono, così puoi continuare a sincronizzare aperture e clic.
HTML e privacy
Tillor mostra l'HTML al personale come lo ha ricevuto il cliente, ma lo tratta come contenuto non attendibile:
- Al salvataggio vengono rimossi script, moduli, iframe, embed e attributi di evento (
onclick, ...). I link si aprono in una nuova scheda - L'anteprima gira in un frame isolato senza script e senza accesso alla sessione di Tillor
- Immagini e caratteri esterni non si caricano automaticamente, così aprire una notifica non attiva un pixel di tracciamento. Il membro del personale può caricare le immagini per ogni notifica
Non contare quindi sul fatto che il tracciamento "aperto" nel tuo sistema scatti quando un membro del personale guarda la notifica.
Cosa Tillor non fa con le notifiche esterne
- Non le invia (di nuovo) né le ritenta automaticamente
- Non recupera aggiornamenti di stato dal tuo provider di posta: sei tu a tenere aggiornato lo stato con
PATCH - Non le conta negli elenchi Notifiche non riuscite, Notifiche respinte e Notifiche in attesa né nei contatori in cima al riepilogo delle notifiche, perché Tillor non può verificare il tuo stato. Compaiono invece sotto Comunicazioni recenti
Webhook e SSE
| Evento | Quando |
|---|---|
notification-delivery:updated | Alla registrazione e a ogni PATCH che cambia qualcosa. Contiene la notifica completa |
notification-delivery:deleted | Con DELETE. Contiene solo id, source, externalSource, externalReference, customerId e invoiceId |
Il campo source è EXTERNAL per le tue registrazioni e INTERNAL per le notifiche di Tillor. Filtra su di esso se vuoi saltare i tuoi eventi. Vedi Webhook e SSE.