Événements Webhook

Le catalogue d'événements de MailLand définit 21 types d'événements répartis en 6 catégories (2 des 21 sont des notices de plateforme auxquelles vous ne pouvez pas vous abonner). Chaque événement est transmis sous forme de requête HTTP POST signée vers votre point de terminaison webhook.

Catalogue d'événementsCopier le lien de la section

Récupérez le catalogue complet des événements de manière programmatique :

GET https://api.mail.land/v1/webhooks/catalog

curl -X GET https://api.mail.land/v1/webhooks/catalog

{
  "version": 1,
  "products": [
    { "id": "transactional", "name": "Transactional Email", "isActive": true, "comingSoon": false },
    { "id": "marketing", "name": "Marketing Email", "isActive": true, "comingSoon": false },
    { "id": "inbound", "name": "Inbound Email", "isActive": true, "comingSoon": false },
    { "id": "system", "name": "System Events", "isActive": true, "comingSoon": false },
    { "id": "validation", "name": "Email Validation", "isActive": false, "comingSoon": true }
  ],
  "categories": [
    {
      "id": "message",
      "name": "Message Events",
      "events": [
        { "id": "message.sent", "name": "Message Sent", "products": ["transactional", "marketing"] },
        { "id": "message.delivered", "name": "Message Delivered", "products": ["transactional", "marketing"] }
      ]
    }
  ]
}

Ce point de terminaison est public (aucune authentification requise) et renvoie toujours la dernière version du catalogue.

Structure standard des donnéesCopier le lien de la section

Chaque livraison webhook inclut une structure externe cohérente :

{
  "event": "message.delivered",
  "event_id": "evt_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5",
  "timestamp": "2026-02-17T12:34:56.789Z",
  "occurred_at": "2026-02-17T12:34:56.120Z",
  "schema_version": 1,
  "data": {
    // Event-specific fields
  }
}

Le data de chaque événement de message contient aussi status_version, status, previous_status, complaint_status et reason, voir Versions de statut.

Versions de statutCopier le lien de la section

Chaque événement de message contient data.status_version, data.status, data.previous_status, data.complaint_status et data.reason. status_version augmente de un chaque fois que MailLand envoie un événement pour un changement du statut du message, de son motif ou de son statut de plainte.

Deux exceptions :

• Un message commence à status_version 0 tant qu'il est queued ou sent. Le passage de queued à sent n'envoie aucun événement et ne change pas la version.
• Plusieurs événements message.deferred peuvent partager la même status_version : un report répété ne change pas le statut.

Les webhooks peuvent arriver dans le désordre et être renvoyés : appliquez-les selon status_version, jamais selon l'ordre d'arrivée.

Un statut peut changer après avoir été final. MailLand signale ce qu'il sait au moment où il le sait. S'il en apprend davantage plus tard, il envoie le nouveau statut avec une status_version plus élevée :

• un message distribué peut rebondir plus tard, lorsque le serveur du destinataire le rejette après coup (un rebond hors bande) ;
• après une panne interne, ou après le rétablissement du serveur de messagerie de MailLand, une distribution ou un refus peut être signalé en retard. Un message failed peut alors devenir bounced ou delivered, un message bounced peut devenir delivered, et un message unknown peut prendre n'importe quel statut final.

Un message ne passe jamais de delivered à failed. MailLand comptabilise ces corrections.

Délais de nouvelle tentativeCopier le lien de la section

MailLand réessaie un message reporté jusqu'à son délai de nouvelle tentative : environ 5 heures après sa première remise à la file de distribution pour le courrier transactionnel, et environ 25 heures pour le courrier marketing. Après ce délai, MailLand ne met plus le message en file pour une nouvelle tentative. Une copie qui attendait déjà une connexion à l'échéance peut encore être tentée ensuite. Ce sont des délais de nouvelle tentative, pas des promesses sur le moment où vous recevez l'événement final. Vous recevez chaque événement dès que le résultat parvient à MailLand ; ce délai n'est pas encore mesuré et peut être plus long lors d'une panne interne. Un message que MailLand n'a pas pu remettre à sa file de distribution dans les 24 heures est terminé comme expired.

Si vous tenez le statut courant d'un message à partir des webhooks (action requise)Copier le lien de la section

C'est un changement de comportement pour les intégrations existantes. Une intégration qui considère message.failed ou message.delivered comme définitifs, et ignore les événements suivants, peut conserver un statut erroné après une correction. Des noms d'événements existants ont désormais de nouvelles séquences possibles.

• Abonnez-vous à tous les événements de message : message.delivered, message.deferred, message.bounced, message.failed, message.complained, message.outcome_unknown et message.retried. Ce n'est qu'ainsi que les événements reçus contiennent chaque changement de statut.
• Enregistrez status_version avec le statut. N'appliquez un événement que si sa status_version est supérieure à celle enregistrée ; un message.deferred de même version ne change rien.
• Continuez à traiter les événements après message.failed, message.bounced ou message.delivered : un événement ultérieur avec une status_version plus élevée remplace le statut précédent.
• Une fois reçus tous les événements jusqu'à la status_version de l'API, votre statut est égal à celui de l'API. L'API peut être en avance sur les webhooks reçus jusque-là et, à status_version 0, elle peut afficher sent sans événement.

Si vous ne vous abonnez qu'à certains événements de message, la status_version la plus élevée reçue n'est pas forcément le statut courant : un type d'événement auquel vous n'êtes pas abonné a pu le changer. Lisez le statut courant via l'API, par exemple pour chaque message dont le dernier événement reçu est message.failed, message.bounced ou message.outcome_unknown, et réconciliez.

Si vous ne pouvez pas modifier votre intégration, interrogez l'API pour le statut des messages qui vous importent. Les intégrations qui se contentent de compter les événements ou d'afficher un historique n'ont rien à changer.

Événements de messageCopier le lien de la section

message.sentCopier le lien de la section

Illustratif : pas encore émis. Cet événement est catalogué mais n'a aucun producteur aujourd'hui.

{
  "event": "message.sent",
  "event_id": "evt_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5",
  "timestamp": "2026-02-17T12:34:56.789Z",
  "data": {
    "message_id": "t_a1b2c3d4e5f6",
    "recipient": "[email protected]",
    "timestamp": "2026-02-17T12:34:56.789Z"
  }
}

message.deliveredCopier le lien de la section

Déclenché lorsque l'e-mail est livré avec succès au serveur de messagerie du destinataire.

Cet événement peut aussi arriver comme correction après un statut final antérieur pour le même message. Voir Versions de statut.

{
  "event": "message.delivered",
  "event_id": "evt_b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "timestamp": "2026-02-17T12:34:58.123Z",
  "data": {
    "message_id": "t_a1b2c3d4e5f6",
    "recipient": "[email protected]",
    "timestamp": "2026-02-17T12:34:58.123Z",
    "smtp_response": "OK",
    "status_version": 1,
    "status": "delivered",
    "previous_status": "sent",
    "complaint_status": "none",
    "reason": null
  }
}

message.deferredCopier le lien de la section

Déclenché lorsque la livraison est temporairement retardée. MailLand réessaiera automatiquement.

Un message peut être reporté plusieurs fois. Le premier report augmente status_version ; les reports suivants portent la même status_version.

{
  "event": "message.deferred",
  "event_id": "evt_c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7",
  "timestamp": "2026-02-17T12:35:00.000Z",
  "data": {
    "message_id": "t_a1b2c3d4e5f6",
    "recipient": "[email protected]",
    "timestamp": "2026-02-17T12:35:00.000Z",
    "smtp_response": "Try again later",
    "bounce_reason": "TransientFailure"
  }
}

message.bouncedCopier le lien de la section

Déclenché lorsqu'un e-mail est rejeté (rebond permanent ou temporaire).

Cet événement peut aussi arriver comme correction après un statut final antérieur pour le même message. Voir Versions de statut.

{
  "event": "message.bounced",
  "event_id": "evt_d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8",
  "timestamp": "2026-02-17T12:35:01.000Z",
  "data": {
    "message_id": "t_a1b2c3d4e5f6",
    "recipient": "[email protected]",
    "timestamp": "2026-02-17T12:35:01.000Z",
    "bounce_type": "hard",
    "bounce_reason": "InvalidRecipient",
    "smtp_response": "The email account that you tried to reach does not exist.",
    "status_version": 1,
    "status": "bounced",
    "previous_status": "sent",
    "complaint_status": "none",
    "reason": "InvalidRecipient"
  }
}

bounce_reason est le jeton de classification que MailLand attribue au rebond (par exemple InvalidRecipient, QuotaIssues, SpamBlock), pas le texte SMTP brut, utilisez smtp_response pour cela. bounce_type vaut hard, soft, blocked ou unknown.

smtp_response est le texte de réponse du serveur destinataire, sans son code de réponse numérique ni son code de statut étendu. bounce_type indique ce que MailLand a fait de l'adresse : hard, mise en suppression pour tous les e-mails ; soft, mise en suppression pour les e-mails marketing pendant 30 jours ; blocked, le refus concernait l'envoi, pas l'adresse (par exemple filtrage anti-spam, authentification de l'expéditeur, réputation ou politique du destinataire), donc rien n'est mis en suppression ; unknown, aucune classification, traité comme soft.

message.failedCopier le lien de la section

Déclenché lorsque MailLand met fin à un message sur la base d'éléments concluants indiquant qu'il n'a pas été distribué, pour une raison du côté de MailLand et non du destinataire. Dans les cas décrits sous Versions de statut, un message.delivered ou un message.bounced peut suivre avec une status_version plus élevée. Le statut du message devient Failed, et non Bounced, et reason indique le cas :

• Le destinataire n'est pas mis en suppression et l'échec n'est pas compté dans votre taux de rebond.
• Un message produit au plus un message.failed. C'est le dernier événement de ce message, sauf si MailLand reçoit plus tard une distribution ou un refus ; un message.delivered ou un message.bounced suit alors avec une status_version plus élevée.

Un refus du serveur de messagerie destinataire est signalé comme message.bounced, jamais comme message.failed.

{
  "event": "message.failed",
  "event_id": "evt_e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0",
  "timestamp": "2026-09-28T02:00:19.1047332Z",
  "data": {
    "message_id": "t_a1b2c3d4e5f6",
    "recipient": "[email protected]",
    "timestamp": "2026-09-28T02:00:18.2522997Z",
    "reason": "dkim_revoked",
    "smtp_response": "Next delivery time PT3.028008S > PT1S",
    "status_version": 1,
    "status": "failed",
    "previous_status": "sent",
    "complaint_status": "none"
  }
}

message.outcome_unknownCopier le lien de la section

Déclenché lorsque MailLand ne peut pas déterminer si un message a atteint sa file de distribution, par exemple parce que la remise a été interrompue et n'a pas pu être établie ensuite. Il est envoyé quelque temps après le délai de nouvelle tentative du message, actuellement 7 jours, si aucun élément n'est arrivé d'ici là. Ce n'est pas un statut final. Le statut devient unknown. Si MailLand apprend le résultat plus tard, vous recevez message.delivered, message.bounced ou message.failed avec une status_version plus élevée.

{
  "event": "message.outcome_unknown",
  "event_id": "evt_0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d",
  "timestamp": "2026-10-08T17:05:00.000Z",
  "data": {
    "message_id": "t_a1b2c3d4e5f6",
    "recipient": "[email protected]",
    "timestamp": "2026-10-08T17:05:00.000Z",
    "status_version": 1,
    "status": "unknown",
    "previous_status": "queued",
    "complaint_status": "none",
    "reason": "handoff_undetermined"
  }
}

message.retriedCopier le lien de la section

Déclenché lorsque vous réessayez un message rebondi ou en échec et que MailLand le remet en file. Le statut devient queued et status_version augmente ; les événements de la copie renvoyée suivent avec des versions plus élevées. Ce n'est pas un statut final.

{
  "event": "message.retried",
  "event_id": "evt_1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e",
  "timestamp": "2026-10-01T18:00:00.000Z",
  "data": {
    "message_id": "t_a1b2c3d4e5f6",
    "recipient": "[email protected]",
    "timestamp": "2026-10-01T18:00:00.000Z",
    "attempt": 1,
    "status_version": 2,
    "status": "queued",
    "previous_status": "bounced",
    "complaint_status": "none",
    "reason": null
  }
}

Événements d'engagementCopier le lien de la section

message.openedCopier le lien de la section

Illustratif : non disponible.

{
  "event": "message.opened",
  "event_id": "evt_f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0",
  "timestamp": "2026-02-17T13:15:00.000Z",
  "data": {
    "message_id": "t_a1b2c3d4e5f6",
    "recipient": "[email protected]",
    "timestamp": "2026-02-17T13:15:00.000Z"
  }
}

message.clickedCopier le lien de la section

Illustratif : non disponible.

{
  "event": "message.clicked",
  "event_id": "evt_g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1",
  "timestamp": "2026-02-17T13:16:00.000Z",
  "data": {
    "message_id": "t_a1b2c3d4e5f6",
    "recipient": "[email protected]",
    "timestamp": "2026-02-17T13:16:00.000Z"
  }
}

message.unsubscribedCopier le lien de la section

Émis lorsqu'un destinataire se désinscrit d'un message que vous avez envoyé : via son en-tête List-Unsubscribe ou son adresse mailto:, le POST en un clic, son lien de désinscription ou la page de préférences. Il n'est pas émis pour les désinscriptions que vous effectuez vous-même via l'API ou le tableau de bord, ni pour les plaintes pour spam (message.complained). Il est envoyé une fois par message, au moment même où le destinataire est désinscrit, à chaque endpoint qui y est abonné. Comme tout événement de message, data porte aussi les champs d'état courants du message (voir Versions de statut).

{
  "event": "message.unsubscribed",
  "event_id": "evt_h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2",
  "timestamp": "2026-02-17T14:00:00.000Z",
  "data": {
    "message_id": "m_a1b2c3d4e5f6",
    "recipient": "[email protected]",
    "timestamp": "2026-02-17T14:00:00.000Z",
    "status_version": 3,
    "status": "delivered",
    "previous_status": "queued",
    "complaint_status": "none",
    "reason": null
  }
}

Événements de suppressionCopier le lien de la section

message.complainedCopier le lien de la section

Déclenché lorsqu'un destinataire marque l'e-mail comme spam (boucle de rétroaction ISP).

{
  "event": "message.complained",
  "event_id": "evt_i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3",
  "timestamp": "2026-02-17T15:00:00.000Z",
  "data": {
    "message_id": "m_a1b2c3d4e5f6",
    "recipient": "[email protected]",
    "timestamp": "2026-02-17T15:00:00.000Z",
    "feedback_type": "abuse"
  }
}

suppression.addedCopier le lien de la section

Illustratif : pas encore émis. Cet événement est catalogué mais n'a aucun producteur aujourd'hui.

{
  "event": "suppression.added",
  "event_id": "evt_j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4",
  "timestamp": "2026-02-17T15:00:01.000Z",
  "data": {
    "email": "[email protected]",
    "type": "complaint",
    "scope": "global",
    "reason": "Spam complaint via ISP feedback loop"
  }
}

suppression.removedCopier le lien de la section

Illustratif : pas encore émis. Cet événement est catalogué mais n'a aucun producteur aujourd'hui.

{
  "event": "suppression.removed",
  "event_id": "evt_k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5",
  "timestamp": "2026-02-17T16:00:00.000Z",
  "data": {
    "email": "[email protected]",
    "type": "manual",
    "scope": "global"
  }
}

Événements entrantsCopier le lien de la section

inbound.receivedCopier le lien de la section

Déclenché lorsqu'un e-mail entrant est reçu sur l'un de vos domaines.

{
  "event": "inbound.received",
  "event_id": "evt_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "timestamp": "2026-02-17T12:00:00.000Z",
  "occurred_at": "2026-02-17T12:00:00.000Z",
  "schema_version": 1,
  "data": {
    "idempotency_key": "r7n2k5x9m1p4w6_s5m3x8k1p7n4w2",
    "email": {
      "id": "r7n2k5x9m1p4w6",
      "received_at": "2026-02-17T12:00:00.000Z",
      "size_bytes": 4521,
      "envelope": {
        "from": "[email protected]",
        "to": ["[email protected]"]
      },
      "headers": {
        "from": { "address": "[email protected]", "name": "Jane Doe" },
        "to": [{ "address": "[email protected]" }],
        "subject": "Help with my order",
        "message_id": "<[email protected]>",
        "date": "2026-02-17T11:59:50.000Z"
      },
      "body": {
        "text_preview": "Hi, I need help with...",
        "has_text": true,
        "has_html": true
      },
      "attachments": [],
      "authentication": {
        "spf": { "result": "pass" },
        "dkim": { "result": "pass" },
        "dmarc": { "result": "pass" }
      },
      "spam": {
        "score": 0.1,
        "is_spam": false,
        "reason": null
      },
      "source": {
        "ip": "203.0.113.10",
        "hostname": "mail.external.com"
      }
    },
    "matched_route": {
      "id": "s5m3x8k1p7n4w2",
      "name": "Support inbox"
    }
  }
}

Événements de compteCopier le lien de la section

account.webhook_pausedCopier le lien de la section

Déclenché lorsqu'un webhook est automatiquement mis en pause en raison d'échecs consécutifs.

{
  "event": "account.webhook_paused",
  "event_id": "evt_m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7",
  "timestamp": "2026-02-17T18:00:00.000Z",
  "data": {
    "webhook_id": "z8m3p1k6x4w2n7",
    "webhook_name": "Production Events",
    "consecutive_failures": 10,
    "last_error": "Connection refused"
  }
}

account.domain_verifiedCopier le lien de la section

Illustratif : pas encore émis. Cet événement est catalogué mais n'a aucun producteur aujourd'hui.

{
  "event": "account.domain_verified",
  "event_id": "evt_n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8",
  "timestamp": "2026-02-17T10:15:00.000Z",
  "data": {
    "domain_id": "q3z8v1k6m9p2x5",
    "domain": "yourdomain.com"
  }
}

account.domain_failedCopier le lien de la section

Illustratif : pas encore émis. Cet événement est catalogué mais n'a aucun producteur aujourd'hui.

{
  "event": "account.domain_failed",
  "event_id": "evt_o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9",
  "timestamp": "2026-02-17T10:15:00.000Z",
  "data": {
    "domain_id": "q3z8v1k6m9p2x5",
    "domain": "yourdomain.com",
    "reason": "DKIM record not found for selector mlnd"
  }
}

account.quota_warningCopier le lien de la section

Illustratif : pas encore émis. Cet événement est catalogué mais n'a aucun producteur aujourd'hui.

{
  "event": "account.quota_warning",
  "event_id": "evt_p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0",
  "timestamp": "2026-02-17T20:00:00.000Z",
  "data": {
    "used": 45000,
    "limit": 50000,
    "percentage": 90
  }
}

account.quota_exceededCopier le lien de la section

Illustratif : pas encore émis. Cet événement est catalogué mais n'a aucun producteur aujourd'hui.

{
  "event": "account.quota_exceeded",
  "event_id": "evt_q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1",
  "timestamp": "2026-02-17T22:00:00.000Z",
  "data": {
    "used": 50000,
    "limit": 50000,
    "percentage": 100
  }
}

Récapitulatif des événementsCopier le lien de la section

« Disponible » correspond à l'indicateur availableNow du catalogue : si quelque chose émet réellement l'événement aujourd'hui. Seuls les événements disponibles peuvent figurer dans un abonnement.

Événements futursCopier le lien de la section

Lorsque includeFutureEvents est true (valeur par défaut), votre webhook reçoit automatiquement les nouveaux types d'événements au fur et à mesure qu'ils sont ajoutés à vos produits abonnés. Définissez-le sur false pour verrouiller votre abonnement à l'instantané actuel des événements.

Les événements marqués « Pas encore » ci-dessus deviennent abonnables lorsque leurs producteurs sont livrés : les noms d'événements et les structures de données documentés ici ne changeront pas à ce moment-là.

Prochaines étapesCopier le lien de la section

• Vérification de signature : vérifiez que les événements proviennent de MailLand
• Logique de nouvelles tentatives : comprendre le comportement de réessai
• Présentation des webhooks : créer et gérer des webhooks