Logique de nouvelles tentatives

Lorsqu'une livraison webhook échoue, MailLand réessaie automatiquement avec des délais croissants. Cette page couvre le calendrier de nouvelles tentatives, les statuts de livraison, la gestion des échecs et comment surveiller et relancer des livraisons manuellement.

Calendrier de nouvelles tentativesCopier le lien de la section

Cette section couvre tous les événements livrés par le durable dispatcher : message.*, suppression.*, account.* et inbound.received. Ce qui est propre aux événements entrants se trouve dans Livraisons entrantes ci-dessous.

MailLand réessaie une livraison échouée jusqu'à 6 fois au total, avec un délai croissant avant chaque nouvelle tentative :

Si la 6e tentative échoue, la livraison est marquée comme définitivement échouée : il n'y a pas d'attente supplémentaire ni de 7e tentative.

Retryable vs Non-retryableCopier le lien de la section

Réponses retryablesCopier le lien de la section

Ces codes de statut déclenchent des nouvelles tentatives automatiques :

• 408 Request Timeout
• 429 Too Many Requests
• 500 Internal Server Error
• 502 Bad Gateway
• 503 Service Unavailable
• 504 Gateway Timeout
• Erreurs réseau (délais d'attente, erreurs de socket, échecs DNS)

Réponses non-retryablesCopier le lien de la section

Ces codes de statut sont traités comme des échecs permanents, pas de nouvelle tentative :

• 400 Bad Request
• 401 Unauthorized
• 403 Forbidden
• 404 Not Found
• Toutes les autres erreurs 4xx (sauf 408 et 429)
• Une réponse de redirection qui échoue la validation (voir Redirections) ou dépasse la limite de sauts

RedirectionsCopier le lien de la section

MailLand ne traite pas votre endpoint comme le ferait un navigateur. Les redirections sont suivies manuellement, avec un maximum de 3 sauts, et chaque saut est revalidé avant que quoi que ce soit ne lui soit envoyé :

• la cible doit être en https:// : une redirection vers http:// est refusée, pas rétrogradée ;
• la cible doit résoudre vers une adresse publique : une redirection vers une adresse privée, loopback ou link-local est refusée, et la requête n'est jamais émise ;
• dépasser 3 sauts fait échouer la livraison.

Une redirection refusée est signalée comme un échec de livraison sans code de statut. Si votre endpoint a changé d'adresse, pointez le webhook vers la nouvelle URL plutôt que de compter sur une redirection.

Configuration de la livraisonCopier le lien de la section

Livraisons entrantesCopier le lien de la section

inbound.received est livré par le même durable dispatcher que tous les autres événements, avec le même calendrier de nouvelles tentatives, la même prise en compte de Retry-After, le même historique de livraison et la même mise en pause automatique que ci-dessus.

• Dédupliquez sur event_id (égal à X-MLND-Event-Id), comme pour tout autre événement. Il est stable par message entrant et par webhook : chaque tentative pour le même e-mail porte le même identifiant.
• Un rejeu manuel est un nouvel événement : un nouvel event_id, l'original figurant dans data.replay_of. data.idempotency_key reste identique.
• La download_url de chaque pièce jointe est signée à chaque tentative et reste valide 15 minutes à partir de là ; l'id de la pièce jointe est le même à chaque tentative. Voir Webhooks entrants.

Afficher l'historique des livraisonsCopier le lien de la section

Consultez les livraisons passées pour un webhook :

GET https://api.mail.land/v1/webhooks/{id}/deliveries

curl -X GET "https://api.mail.land/v1/webhooks/wh_abc123/deliveries?limit=20" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Paramètres de requêteCopier le lien de la section

{
  "items": [
    {
      "publicId": "p8r2kx7m9wq4rtz",
      "eventType": "message.delivered",
      "messageId": "t_a1b2c3d4e5f6",
      "statusCode": 200,
      "responseTimeMs": 145,
      "success": true,
      "errorMessage": null,
      "createdAt": "2026-02-17T12:34:58.000Z",
      "attemptNumber": 1
    },
    {
      "publicId": "p8r2kx7m3nq1abc",
      "eventType": "message.bounced",
      "messageId": "t_d4e5f6a1b2c3",
      "statusCode": 503,
      "responseTimeMs": 15000,
      "success": false,
      "errorMessage": "Service Unavailable",
      "createdAt": "2026-02-17T12:30:00.000Z",
      "attemptNumber": 3
    }
  ],
  "nextCursor": "eyJ2IjoxLCJzIjoiY3JlYXRlZGF0OmRlc2MiLCJrIjoi...",
  "hasMore": true
}

Relancer une livraison échouéeCopier le lien de la section

Relancez manuellement une livraison échouée spécifique :

POST https://api.mail.land/v1/webhooks/{id}/deliveries/{publicId}/retry

curl -X POST https://api.mail.land/v1/webhooks/wh_abc123/deliveries/p8r2kx7m3nq1abc/retry \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Retourne 202 Accepted en cas de succès. La nouvelle tentative est mise en file d'attente et utilise la charge utile d'événement originale.

Mise en pause automatique en cas d'échecsCopier le lien de la section

Lorsqu'un webhook accumule suffisamment de tentatives de livraison échouées consécutives, MailLand le met automatiquement en pause. Le seuil est le pauseThreshold propre au webhook s'il est défini à une valeur supérieure à 0, sinon la valeur par défaut de 10 tentatives de livraison échouées consécutives :

1. L'isActive du webhook est mis à false, et pausedAt / pausedReason sont renseignés : pausedReason indique le nombre d'échecs et la nature du dernier
2. Une notification in-app est créée
3. Aucun autre événement n'est livré jusqu'à la reprise du webhook

Le compteur porte sur les tentatives, pas sur les événements : un seul événement qui épuise toute son échelle de nouvelles tentatives contribue à plusieurs échecs.

Il n'y a pas de notification d'avertissement plus tôt avant que le seuil ne soit atteint : vérifiez consecutiveFailures de manière proactive (voir Bonnes pratiques ci-dessous) plutôt que d'attendre d'en être informé.

Reprendre un webhook mis en pauseCopier le lien de la section

POST https://api.mail.land/v1/webhooks/{id}/resume

curl -X POST https://api.mail.land/v1/webhooks/wh_abc123/resume \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Cela réactive le webhook : cela efface l'état de pause, réinitialise le compteur d'échecs consécutifs à zéro, et le remet actif. La prochaine tentative de livraison d'événement sera effectuée normalement.

Bonnes pratiquesCopier le lien de la section

• Retournez 200 rapidement : traitez les charges utiles webhook de manière asynchrone. Mettez l'événement en file d'attente et retournez 200 immédiatement. Les gestionnaires de longue durée risquent des délais d'attente.
• Utilisez l'ID d'événement pour un traitement idempotent : l'en-tête X-MLND-Event-Id (et le champ event_id correspondant dans la charge utile) est stable à travers les nouvelles tentatives et les rediffusions : le même événement sous-jacent arrive toujours avec le même identifiant, quel que soit le nombre de fois où il est redistribué. Stockez les identifiants traités et ignorez ceux déjà gérés, afin qu'une livraison en double soit un no-op de votre côté.
• Surveillez les échecs consécutifs : vérifiez le champ consecutiveFailures lors de la liste des webhooks. Enquêtez avant d'atteindre le seuil de mise en pause automatique.
• Gérez correctement le 429 : si votre point de terminaison est surchargé, retournez 429 avec un en-tête Retry-After. MailLand le respectera.

Prochaines étapesCopier le lien de la section

• Vérification de signature : vérifier l'authenticité du webhook
• Événements : référence complète des types d'événements
• Présentation des webhooks : créer et gérer des webhooks