Notificaciones externas
Registra los correos que tu propio sistema envió a un cliente, para que el personal los vea en Tillor
Última actualización el
¿Tu sistema envía por su cuenta correos a clientes (boletín, confirmación de reserva, recordatorio)? Regístralos entonces en Tillor. El personal los ve en el cliente, en la factura y en el resumen Notificaciones, junto a las notificaciones que envía el propio Tillor.
Tillor no envía nada: registras un mensaje que ya se ha enviado. Las notificaciones externas llevan siempre en la aplicación la etiqueta Externa con el nombre de tu fuente, para que nunca se confundan con una notificación de Tillor.
Acceso
El usuario detrás de la clave de API necesita en la organización uno de estos permisos. Un administrador los concede en los permisos de usuario de la organización, en el grupo Notificaciones (Registrar notificaciones externas y Gestionar notificaciones externas de otros).
| Permiso | Qué puedes hacer |
|---|---|
notifications:external:write | Registrar notificaciones y actualizar o eliminar tus propios registros |
notifications:external:manage-others | También actualizar o eliminar registros de otros usuarios o integraciones |
Un usuario por integración
La propiedad depende del usuario de la clave de API. Usa para cada integración un usuario (de servicio) propio, y así una integración nunca podrá modificar las notificaciones de otra.
Endpoints
Todas las rutas están bajo /api/orgs/:orgId. Esquemas exactos: OpenAPI, etiqueta notifications.
| Method | Ruta | Descripción |
|---|---|---|
| POST | /notifications/external | Registrar una notificación |
| PATCH | /notifications/external/{id} | Actualizar el estado, las marcas de tiempo o el contenido |
| DELETE | /notifications/external/{id} | Eliminar definitivamente |
| GET | /notifications?source=EXTERNAL | Listar las notificaciones registradas (filtra también por externalSource, externalReference, customerId, invoiceId) |
| GET | /notifications/{id} | Obtener una notificación |
Las notificaciones que envió el propio Tillor no se pueden modificar ni eliminar con estos endpoints; devuelven 404.
Registrar
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 }]
}
}'Todos los campos y límites están en OpenAPI. Estos campos tienen reglas que debes conocer de antemano:
| Campo | Regla |
|---|---|
externalSource | Nombre de tu sistema en minúsculas, cifras, ., _ o - (p. ej. mailchimp). El personal ve este nombre en la notificación |
externalReference | Tu propio ID para este mensaje, único dentro de externalSource |
name | Etiqueta breve para el personal (p. ej. "Confirmación de reserva"). Se puede buscar por ella |
customerId / invoiceId | Al menos uno de los dos. Determina dónde aparece la notificación. Si solo envías invoiceId, Tillor vincula también al cliente de esa factura. Un ID desconocido, o una factura de otro cliente, da 400 |
status | SENT, FAILED, BOUNCED o COMPLAINED. Sin sentAt con SENT, Tillor usa el momento del registro |
sentAt, readAt, clickedAt | ISO 8601 con zona horaria, p. ej. 2026-09-19T08:15:00Z. Se rechazan otros valores |
email.attachments | Solo metadatos (filename, contentType, size). Los archivos en sí no se guardan |
Reintentar con seguridad
POST es idempotente en externalSource + externalReference. Si envías de nuevo la misma combinación (por ejemplo tras un tiempo de espera agotado), recibes la notificación existente y no se modifica nada. Si quieres cambiar algo, usa PATCH.
Sin datos personales en externalReference ni name
externalSource, externalReference y name se guardan sin cifrar porque se busca por ellos. Usa un ID técnico, no una dirección de correo ni un nombre. Un externalReference con @ se rechaza. El destinatario, el asunto, el contenido y los adjuntos sí se guardan cifrados.
Actualizar y eliminar
Con PATCH envía solo los campos que cambian, por ejemplo cuando un correo rebota a posteriori:
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 notificación definitivamente, incluido su contenido. Úsalo también para atender una solicitud de eliminación (RGPD).
Un PATCH que no cambia nada no hace nada: ni cambio ni evento. Si modificas el contenido (etiqueta, destinatario, remitente, asunto, texto, HTML o adjuntos) o eliminas una notificación, queda en el registro de actividad del cliente o de la factura, con el usuario que lo hizo. Las actualizaciones de estado, readAt o clickedAt no aparecen ahí, para que puedas seguir sincronizando aperturas y clics.
HTML y privacidad
Tillor muestra el HTML al personal tal como lo recibió el cliente, pero lo trata como contenido no fiable:
- Al guardar se eliminan scripts, formularios, iframes, embeds y atributos de evento (
onclick, ...). Los enlaces se abren en una pestaña nueva - La vista previa se ejecuta en un marco aislado, sin scripts y sin acceso a la sesión de Tillor
- Las imágenes y fuentes externas no se cargan automáticamente, para que abrir una notificación no active un píxel de seguimiento. El empleado puede cargar las imágenes por notificación
Por tanto, no cuentes con que el seguimiento de "abierto" salte en tu sistema cuando un empleado mira la notificación.
Lo que Tillor no hace con las notificaciones externas
- No las (re)envía ni reintenta automáticamente
- No recupera actualizaciones de estado de tu proveedor de correo: tú mantienes el estado al día con
PATCH - No las cuenta en las listas Notificaciones fallidas, Notificaciones rebotadas y Notificaciones pendientes ni en los contadores de arriba del resumen de notificaciones, porque Tillor no puede verificar tu estado. Sí aparecen en Comunicaciones recientes
Webhooks y SSE
| Evento | Cuándo |
|---|---|
notification-delivery:updated | Al registrar y en cada PATCH que cambia algo. Contiene la notificación completa |
notification-delivery:deleted | Con DELETE. Contiene solo id, source, externalSource, externalReference, customerId y invoiceId |
El campo source es EXTERNAL para tus registros e INTERNAL para las notificaciones de Tillor. Filtra por él si quieres saltarte tus propios eventos. Consulta Webhooks y SSE.