Webhooks transactionnels

Les webhooks permettent à votre application de recevoir des notifications en temps réel lorsqu'il se passe quelque chose avec un e-mail transactionnel après son envoi. Au lieu d'interroger l'API pour vérifier le statut de livraison, Flexmail envoie une requête HTTP POST à votre point de terminaison au moment où un événement se produit.

C'est particulièrement utile pour les e-mails transactionnels : vous pouvez agir immédiatement lorsqu'une réinitialisation de mot de passe rebondit, lorsqu'une confirmation de commande est livrée, ou lorsqu'un destinataire signale un message comme spam.

Événements webhook

Flexmail envoie une notification webhook pour chacun des événements suivants :


  • Envoyé — le message a été accepté et transmis au serveur de messagerie destinataire.
  • Rejeté — le message a été rejeté par Flexmail et n'a pas été envoyé.
  • Livré — le serveur de messagerie destinataire a confirmé la livraison dans la boîte aux lettres du destinataire.
  • Rebondi — la livraison a échoué. Les rebonds définitifs indiquent un problème permanent (l'adresse n'existe pas) ; les rebonds temporaires indiquent un problème temporaire (boîte aux lettres pleine, serveur indisponible).
  • Ouvert — le destinataire a ouvert le message.
  • Cliqué — le destinataire a cliqué sur un lien suivi dans le message.

Attention Le suivi des ouvertures et des clics nécessite que les pixels de suivi et l'encapsulation des liens soient activés. Les événements de livraison dépendent du serveur de messagerie destinataire qui confirme la livraison — tous les serveurs ne le font pas.

Configurer un point de terminaison webhook

Votre point de terminaison webhook est une URL sur votre serveur qui accepte les requêtes HTTP POST et renvoie une réponse 200 pour accuser réception.


Exigences pour votre point de terminaison

  • Accepte les requêtes HTTP POST.
  • Est accessible publiquement via HTTPS.
  • Renvoie un code de statut HTTP 2xx dans un délai raisonnable pour confirmer la réception.
  • Traite le payload de manière asynchrone si votre logique de traitement est lente — répondez immédiatement et traitez en arrière-plan pour éviter les délais d'expiration.

Enregistrer votre point de terminaison dans Flexmail

La configuration du point de terminaison webhook se fait via l'API. Le processus d'enregistrement complet et les options disponibles sont documentés dans la documentation de l'API sur email-api.flexmail.eu/documentation, dans la section Webhooks.

Payload webhook

Chaque notification webhook est une requête HTTP POST avec un corps JSON. Le payload contient le type d'événement, un horodatage, l'ID du message et l'adresse e-mail du destinataire. Selon l'événement, des champs supplémentaires sont inclus — par exemple, un événement de rebond inclut le type de rebond et la raison, et un événement de clic inclut l'URL qui a été cliquée.


Un payload typique ressemble à ceci :

{
    "event": "delivered",
    "timestamp": "2024-11-15T09:32:00Z",
    "messageId": "abc123",
    "recipient": "customer@example.com"
}

La spécification complète du payload pour chaque type d'événement se trouve dans la documentation de l'API: email-api.flexmail.eu/documentation/webhooks.

Que faire avec les événements webhook


Rebonds

Lorsque vous recevez un événement de rebond définitif, signalez cette adresse e-mail dans votre système. Arrêtez d'envoyer à cette adresse et vérifiez si elle a été saisie correctement. Continuer à envoyer à des adresses ayant subi un rebond définitif nuit à votre réputation d'expéditeur.


Plaintes pour spam

Lorsqu'un destinataire signale un e-mail transactionnel comme spam, supprimez immédiatement cette adresse. Même si l'e-mail était véritablement transactionnel (une confirmation de commande, par exemple), le destinataire a signalé qu'il ne souhaite pas recevoir d'e-mails de votre part. Continuer à envoyer est préjudiciable à votre réputation et peut avoir des conséquences juridiques.


Confirmations de livraison

Pour les messages sensibles au facteur temps comme les réinitialisations de mot de passe ou les codes d'authentification à deux facteurs, vous pouvez utiliser l'événement de livraison pour confirmer que l'e-mail a atteint la boîte de réception. Si aucune confirmation de livraison n'arrive dans un délai raisonnable, vous pouvez afficher un message dans votre interface suggérant à l'utilisateur de vérifier son dossier spam ou de réessayer.


Conseil de support Accusez réception des requêtes webhook immédiatement avec une réponse 200, puis traitez le payload dans une tâche en arrière-plan ou une file d'attente. Si votre gestionnaire met trop de temps à répondre, Flexmail peut expirer et réessayer la requête, ce qui peut entraîner un traitement en double.

Nouvelles tentatives

Si votre point de terminaison ne renvoie pas une réponse réussie, Flexmail réessaie la notification webhook. Rendez votre gestion des événements idempotente : traiter deux fois le même événement doit produire le même résultat que le traiter une seule fois. Utilisez l'ID du message et le type d'événement ensemble pour dédupliquer.

Étapes suivantes

Est-ce que cela a répondu à ta question? Merci pour les commentaires Un problème est survenu lors de l'envoi de vos commentaires. Veuillez réessayer plus tard.

Vous n'avez pas trouvé ce que vous cherchiez? Contactez-nous Contactez-nous