Événements et webhooks
Connexion des webhooks
Spécifiez l'adresse de réception des webhooks dans vos paramètres d'intégration. Il recevra des notifications sur les nouvelles lettres, l'état des boîtes aux lettres et les résultats des opérations.
Dans les paramètres d'intégration, définissez un secret de webhook distinct et activez la livraison. Ce secret est utilisé pour vérifier les signatures de notification ; mail API-key ne convient pas pour cela.
Format des notifications
La notification arrive HTTP POST- demande avec Content-Type: application/json. Le champ event contient le type d'événement, timestamp — heure de notification, data — données d'événement. La composition de data dépend de l'événement.
L'identifiant data.event_id permet de reconnaître la relivraison. Stockez-le avec votre ID d'intégration et traitez un événement une seule fois.
{ "event": "mail.message.received", "timestamp": "2026-11-01T12:00:00Z", "data": { "event_id": "00000000-0000-4000-8000-000000000001", "created_at": "2026-11-01T12:00:00Z", "mailbox_id": 42, "folder": "INBOX", "uidvalidity": 123456, "uid": 120 }}Vérification et confirmation
L'en-tête X-Webhook-Signature contient HMAC-SHA256 en notation hexadécimale minuscule. Calculez la signature à partir des octets d'origine du corps de la requête et du secret du webhook. Vérifiez la signature avant de traiter les données ; la re-sérialisation de JSON modifiera les octets signés.
Après avoir vérifié la signature et sauvegardé l'événement, renvoyez HTTP 200 ou 201. Les réponses 202 et 204 n'accusent pas réception. Répondez dans les 10 secondes ; Effectuez un traitement long après avoir enregistré l'événement.
Les notifications peuvent arriver à plusieurs reprises et dans le désordre. Avant de modifier le statut de l'abonnement, vérifiez ses détails actuels. L'historique des livraisons est disponible dans les paramètres d'intégration.
Quels événements se produisent
mailbox.created- La box est créée et prête à l'emploi.
mailbox.expiring- La fin de la période payante de la box approche.
mailbox.renewed- La période de paiement de la box a été allongée.
mailbox.suspended- L'accès à la boîte mail est suspendu : la lecture et l'envoi sont indisponibles.
mailbox.resumed- L'accès à la boîte aux lettres a été rétabli.
mailbox.deleting_soon- Il reste une heure avant la suppression de la case impayée.
mailbox.deleted- La boîte a été supprimée.
mailbox.account_changed- La boîte aux lettres est liée à un autre compte de messagerie.
mail.message.received- Une nouvelle lettre entrante est apparue dans la boîte aux lettres.
mail.operation.succeeded- L'opération s'est déroulée avec succès. Pour l'envoi, cela signifie l'acceptation de la lettre par le serveur de messagerie, plutôt que sa remise dans la boîte de réception du destinataire.
mail.operation.failed- L'opération a échoué.
mail.operation.uncertain- Le résultat de l'envoi est inconnu. Veuillez vérifier l'état avant de renvoyer.
Rappels de paiement : 14, 7, 3, 2, 1 jour et une heure avant l'expiration. Le renouvellement annule les rappels obsolètes qui n'ont pas encore été envoyés.