Webhooks entrants

Lorsqu'un e-mail entrant correspond à une route dont les actions incluent webhook, MailLand envoie l'e-mail analysé au webhook de cette route sous forme de requête POST JSON. Cette page décrit le format du payload, la vérification de signature et le comportement de livraison.

Payload du webhookCopier le lien de la section

MailLand envoie une requête POST à votre URL de webhook avec le corps JSON suivant :

{
  "event": "inbound.received",
  "event_id": "evt_a1b2c3d4e5f60718293a4b5c6d7e8f90",
  "timestamp": "2026-02-17T14:30:00Z",
  "occurred_at": "2026-02-17T14:29:58Z",
  "schema_version": 1,
  "data": {
    "idempotency_key": "k7m2x9q4p1w8z3_r7k3m9q2p4w8x1",
    "email": {
      "id": "k7m2x9q4p1w8z3",
      "received_at": "2026-02-17T14:29:58Z",
      "size_bytes": 48213,
      "envelope": {
        "from": "[email protected]",
        "to": ["[email protected]"]
      },
      "headers": {
        "from": { "address": "[email protected]", "name": "Jane Customer" },
        "to": [{ "address": "[email protected]", "name": null }],
        "cc": [],
        "subject": "Need help with my account",
        "message_id": "<[email protected]>",
        "in_reply_to": null,
        "reply_to": "[email protected]",
        "date": "2026-02-17T14:29:55Z"
      },
      "body": {
        "text_preview": "I need assistance with my account settings.",
        "has_text": true,
        "has_html": true
      },
      "attachments": [
        {
          "id": "a3k7m2q9p4w1x8",
          "file_name": "screenshot.png",
          "content_type": "image/png",
          "size_bytes": 34500,
          "is_inline": false,
          "content_id": null,
          "download_url": "https://r2.example.com/screenshot.png?X-Amz-Signature=..."
        }
      ],
      "authentication": {
        "spf": { "result": "pass" },
        "dkim": { "result": "pass" },
        "dmarc": { "result": "pass" }
      },
      "spam": {
        "score": 1.2,
        "is_spam": false,
        "reason": null
      },
      "source": {
        "ip": "203.0.113.42",
        "hostname": "mail.example.com"
      }
    },
    "matched_route": {
      "id": "r7k3m9q2p4w8x1",
      "name": "Support Inbox"
    }
  }
}

Le corps complet de l'e-mail n'est jamais inclus en ligne : seulement un aperçu tronqué text_preview et les indicateurs has_text/has_html. Il n'y a pas de champ body.html.

Les champs sans valeur (name, in_reply_to, content_id, reason, data.matched_route, etc.) sont totalement omis du JSON plutôt qu'envoyés comme null. L'exemple ci-dessus montre null par lisibilité ; ne comptez pas sur la présence de la clé.

Champs du payloadCopier le lien de la section

Pièces jointesCopier le lien de la section

Le contenu des pièces jointes n'est jamais inclus en ligne. Chaque entrée de data.email.attachments porte une download_url :

GET https://api.mail.land/v1/transactional/inbound/emails/{emailId}/raw

Vérification de signatureCopier le lien de la section

Les webhooks entrants sont signés exactement comme tout autre webhook MailLand : même en-tête, même schéma, même gestion du secret. La référence canonique, avec un exemple détaillé et du code de vérification en huit langages, est Signature Verification ; tout ce qui y est décrit s'applique ici sans changement.

En résumé :

X-MLND-Signature: t=1708171200,v1=<hex>

• t est un horodatage Unix en secondes, v1 est un HMAC-SHA256 en hexadécimal minuscule ;
• la chaîne signée est {timestamp}.{raw_body} : l'horodatage, un point littéral, puis le corps exactement tel que reçu, avant l'analyse JSON ;
• la clé est le secret de signature du webhook, affiché une seule fois à sa création ;
• comparez en temps constant et rejetez un horodatage vieux de plus de 300 secondes.

Comportement de livraisonCopier le lien de la section

Codes de réponseCopier le lien de la section

Votre point de terminaison doit répondre avec un code de statut 2xx pour accuser réception. Tout le reste, un statut autre que 2xx ou un délai dépassé, compte comme une tentative de livraison échouée.

Politique de nouvelles tentativesCopier le lien de la section

Une tentative échouée est rejouée selon le même calendrier que tout autre événement webhook, jusqu'à 6 tentatives au total par événement : la première tentative, puis des nouvelles tentatives immédiatement, après 1 minute, 5 minutes, 15 minutes et 1 heure. Après la 6ᵉ tentative échouée, la livraison est marquée comme définitivement échouée. Vous pouvez la rejouer manuellement. Voir Logique de nouvelle tentative pour le calendrier complet.

Rejouer un webhookCopier le lien de la section

Relivrer le webhook pour un e-mail entrant spécifique :

POST https://api.mail.land/v1/transactional/inbound/emails/{id}/replay-webhook

curl -X POST https://api.mail.land/v1/transactional/inbound/emails/k7m2x9q4p1w8z3/replay-webhook \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

{
  "emailId": "k7m2x9q4p1w8z3",
  "queued": true,
  "webhookUrl": "https://yourapp.com/webhooks/support",
  "message": "Webhook replay queued successfully"
}

Cela met en file une livraison durable vers le webhook de la route correspondante et renvoie 202 Accepted une fois cette ligne validée ; l'envoi n'est pas synchrone. Le rejeu reçoit un ID d'événement nouveau (un nouvel event_id et un nouvel X-MLND-Event-Id) et porte l'ID de la livraison d'origine dans data.replay_of : votre déduplication le traite donc comme un nouvel événement, tout en vous permettant de le rattacher à l'original. data.idempotency_key reste identique à celui de la livraison d'origine. La requête porte X-MLND-Source: inbound et X-MLND-Inbound-Email-Id, et chaque download_url de pièce jointe du payload est signée au moment de l'envoi : elle est valable 15 minutes à partir de ce moment, et non à partir de l'appel au rejeu.

Dédupliquer les événementsCopier le lien de la section

La livraison des webhooks entrants est au moins une fois (at-least-once) : une nouvelle tentative, un délai dépassé de votre côté alors que la requête a déjà été traitée, ou un relais entre workers peut livrer le même événement plus d'une fois. Les récepteurs doivent dédupliquer.

• Chaque webhook entrant porte un ID d'événement stable dans event_id et dans l'en-tête X-MLND-Event-Id. Il est déterministe par message entrant et par webhook : toutes les tentatives de livraison du même message vers le même webhook ont donc le même ID.
• Dédupliquez sur cet ID. Conservez les ID traités et ignorez tout ID déjà vu.
• Un rejeu manuel est un nouvel événement. Il a un nouvel event_id et un champ data.replay_of contenant l'ID d'origine. Si vous voulez qu'un rejeu soit ignoré lorsque l'original a déjà été traité, comparez aussi data.replay_of à vos ID stockés.

app.post("/webhooks/support", express.raw({ type: "application/json" }), async (req, res) => {
  // 1. Verify X-MLND-Signature first (see Signature Verification).
  const eventId = req.header("X-MLND-Event-Id");
  const client = await db.connect();
  try {
    await client.query("BEGIN");
    // 2. Record the event id; the unique constraint makes this atomic.
    const inserted = await client.query(
      "INSERT INTO processed_events (event_id) VALUES ($1) ON CONFLICT (event_id) DO NOTHING",
      [eventId],
    );
    // 3. Only a first-time id enqueues work, in the SAME transaction (jobs table).
    if (inserted.rowCount > 0) {
      await client.query("INSERT INTO jobs (kind, payload) VALUES ($1, $2)", [
        "process-inbound-email",
        req.body.toString(),
      ]);
    }
    await client.query("COMMIT");
    res.sendStatus(200); // new or duplicate: acknowledge
  } catch (err) {
    await client.query("ROLLBACK"); // id and job are both undone, so the retry is not a "duplicate"
    res.sendStatus(500);
  } finally {
    client.release();
  }
});

Enregistrer l'ID et mettre le travail en file dans une seule transaction est essentiel : si l'ID était enregistré d'abord et que la mise en file échouait, la nouvelle tentative de MailLand serait ignorée comme doublon et l'e-mail serait perdu.

Conservez les ID traités au moins aussi longtemps que votre plus longue fenêtre de nouvelles tentatives, plus tout rejeu que vous pourriez déclencher.

En-têtes du webhookCopier le lien de la section

Chaque requête webhook inclut les en-têtes suivants :

Bonnes pratiquesCopier le lien de la section

• Répondez rapidement : accusez réception du webhook avec 200 immédiatement et traitez l'e-mail de manière asynchrone dans une tâche de fond.
• Vérifiez les signatures : validez toujours l'en-tête X-MLND-Signature pour empêcher les payloads falsifiés.
• Gérez les doublons : la livraison est au moins une fois ; dédupliquez donc sur X-MLND-Event-Id (l'event_id du payload). Un rejeu manuel a un nouvel ID et data.replay_of désigne l'original ; voir Dédupliquer les événements.
• Téléchargez les pièces jointes immédiatement : chaque download_url expire 15 minutes après la génération du payload ; ensuite, récupérez le message brut.
• Utilisez HTTPS : les URL de webhook doivent utiliser HTTPS en production pour une livraison sécurisée du payload.

Réponses d'erreurCopier le lien de la section

Étapes suivantesCopier le lien de la section

• Inbound Overview : configurer les paramètres entrants et consulter les e-mails
• Inbound Routes : configurer les règles de routage pour la livraison des webhooks
• Webhooks : configuration des webhooks sortants pour les événements d'e-mail