Notificações externas
Registe e-mails que o seu próprio sistema enviou a um cliente, para que a equipa os volte a ver no Tillor
Última atualização em
O seu sistema envia e-mails aos clientes por conta própria (newsletter, confirmação de reserva, lembrete)? Registe-os então no Tillor. A equipa vê-os no cliente, na fatura e na vista geral Notificações, ao lado das notificações que o próprio Tillor envia.
O Tillor não envia nada: você regista uma mensagem que já foi enviada. As notificações externas têm sempre na aplicação a etiqueta Externa com o nome da sua origem, para que nunca passem por uma notificação do Tillor.
Acesso
O utilizador por trás da chave de API precisa, na organização, de uma destas permissões. Um administrador atribui-as nas permissões de utilizador da organização, no grupo Notificações (Registar notificações externas e Gerir notificações externas de outros).
| Permissão | O que pode fazer |
|---|---|
notifications:external:write | Registar notificações e atualizar ou eliminar os seus próprios registos |
notifications:external:manage-others | Também atualizar ou eliminar registos de outros utilizadores ou integrações |
Um utilizador por integração
A propriedade está associada ao utilizador da chave de API. Use um utilizador (de serviço) próprio por integração; assim, uma integração nunca pode alterar as notificações de outra.
Endpoints
Todos os caminhos estão em /api/orgs/:orgId. Esquemas exatos: OpenAPI, etiqueta notifications.
| Método | Caminho | Descrição |
|---|---|---|
| POST | /notifications/external | Registar uma notificação |
| PATCH | /notifications/external/{id} | Atualizar o estado, as datas e horas ou o conteúdo |
| DELETE | /notifications/external/{id} | Eliminar definitivamente |
| GET | /notifications?source=EXTERNAL | Listar notificações registadas (filtre também por externalSource, externalReference, customerId, invoiceId) |
| GET | /notifications/{id} | Obter uma notificação |
Não pode alterar nem eliminar através destes endpoints notificações que o próprio Tillor enviou; devolvem 404.
Registar
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 os campos e limites estão no OpenAPI. Estes campos têm regras que deve conhecer de antemão:
| Campo | Regra |
|---|---|
externalSource | Nome do seu sistema em minúsculas, algarismos, ., _ ou - (p. ex. mailchimp). A equipa vê este nome na notificação |
externalReference | O seu próprio ID para esta mensagem, único dentro de externalSource |
name | Etiqueta curta para a equipa (p. ex. "Confirmação de reserva"). Pode ser pesquisada |
customerId / invoiceId | Pelo menos um dos dois. Determina onde a notificação aparece. Se enviar apenas invoiceId, o Tillor associa também o cliente dessa fatura. Um ID desconhecido, ou uma fatura de outro cliente, devolve 400 |
status | SENT, FAILED, BOUNCED ou COMPLAINED. Sem sentAt em SENT, o Tillor usa o momento do registo |
sentAt, readAt, clickedAt | ISO 8601 com fuso horário, p. ex. 2026-09-19T08:15:00Z. Outros valores são rejeitados |
email.attachments | Apenas metadados (filename, contentType, size). Os ficheiros em si não são guardados |
Repetir em segurança
POST é idempotente em externalSource + externalReference. Se enviar de novo a mesma combinação (por exemplo, após um tempo limite), recebe a notificação existente de volta e nada é alterado. Se quiser ajustar algo, use PATCH.
Sem dados pessoais em externalReference ou name
externalSource, externalReference e name são guardados sem cifragem, porque são pesquisáveis. Use um ID técnico, não um endereço de e-mail nem um nome. Um externalReference com @ é rejeitado. O destinatário, o assunto, o conteúdo e os anexos são, esses sim, guardados cifrados.
Atualizar e eliminar
Em PATCH envie apenas os campos que mudam, por exemplo quando um e-mail é devolvido mais tarde:
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 a notificação definitivamente, incluindo o conteúdo. Use-o também para satisfazer um pedido de eliminação (RGPD).
Um PATCH que não altera nada não faz nada: sem alteração, sem evento. Se alterar o conteúdo (etiqueta, destinatário, remetente, assunto, texto, HTML ou anexos) ou eliminar uma notificação, isso fica no registo de atividade do cliente ou da fatura, com o utilizador que o fez. As atualizações de estado, readAt ou clickedAt não aparecem aí, para que possa continuar a sincronizar aberturas e cliques.
HTML e privacidade
O Tillor mostra o HTML à equipa tal como o cliente o recebeu, mas trata-o como conteúdo não fidedigno:
- Ao guardar, são removidos scripts, formulários, iframes, embeds e atributos de evento (
onclick, ...). As ligações abrem num novo separador - A pré-visualização corre numa moldura isolada, sem scripts e sem acesso à sessão do Tillor
- As imagens e os tipos de letra externos não são carregados automaticamente, para que abrir uma notificação não ative um pixel de rastreio. O membro da equipa pode carregar as imagens por notificação
Por isso, não conte com que o rastreio de "aberto" no seu sistema dispare quando um membro da equipa vê a notificação.
O que o Tillor não faz com notificações externas
- Não (re)envia nem volta a tentar automaticamente
- Não vai buscar atualizações de estado ao seu fornecedor de e-mail: é você que mantém o estado atual com
PATCH - Não conta nas listas Notificações falhadas, Notificações devolvidas e Notificações pendentes nem nos contadores no topo da vista geral de notificações, porque o Tillor não pode verificar o seu estado. Aparecem, sim, em Comunicações recentes
Webhooks e SSE
| Evento | Quando |
|---|---|
notification-delivery:updated | Ao registar e em cada PATCH que altere algo. Contém a notificação completa |
notification-delivery:deleted | Em DELETE. Contém apenas id, source, externalSource, externalReference, customerId e invoiceId |
O campo source é EXTERNAL para os seus registos e INTERNAL para notificações do Tillor. Filtre por ele se quiser ignorar os seus próprios eventos. Veja Webhooks e SSE.