Si votre serveur ne répond pas à un webhook, Mailpro considère la livraison comme un échec et la renvoie automatiquement 7 fois, avec des délais croissants sur un peu plus d'une journée. Après 10 échecs consécutifs, le webhook est désactivé et vous devez le réactiver une fois votre serveur corrigé.
Qu'est-ce qu'une livraison réussie ou en échec ?
Une livraison est considérée réussie quand votre URL répond avec un code HTTP 2xx en moins de 10 secondes. Tout autre résultat (délai dépassé, 4xx, 5xx, erreur réseau) est un échec.
| Réponse de votre serveur | Résultat |
|---|---|
| 200, 201, 204… en moins de 10 s | Réussite |
| 2xx après plus de 10 s | Échec (délai dépassé) |
| 4xx (401, 404…) ou 5xx (500, 503…) | Échec |
| Pas de réponse, DNS introuvable, certificat invalide | Échec (erreur réseau) |
Combien de fois Mailpro réessaie-t-il ?
Mailpro réessaie automatiquement, avec des délais croissants : 10 s → 1 min → 5 min → 30 min → 2 h → 6 h → 24 h, soit 7 tentatives sur un peu plus d'une journée. Chaque tentative porte l'en-tête X-Mailpro-Attempt et le même X-Mailpro-Event-Id : votre traitement doit donc être idempotent.
| Nouvelle tentative | Délai |
|---|---|
| 1 | 10 secondes |
| 2 | 1 minute |
| 3 | 5 minutes |
| 4 | 30 minutes |
| 5 | 2 heures |
| 6 | 6 heures |
| 7 | 24 heures |
Ces délais croissants laissent à votre serveur le temps de revenir après une panne courte (redémarrage, déploiement) sans le surcharger.
Pourquoi le traitement doit-il être idempotent ?
Un même événement peut vous arriver plusieurs fois : par exemple si votre serveur l'a bien traité mais a répondu après 10 secondes. Être idempotent signifie que recevoir deux fois le même événement produit le même résultat qu'une seule fois. Concrètement : enregistrez chaque X-Mailpro-Event-Id traité, et si un événement arrive avec un identifiant déjà connu, répondez 200 sans rien refaire.
Que se passe-t-il après 10 échecs consécutifs ?
Après 10 échecs consécutifs, le webhook passe à l'état Désactivé et plus aucun événement n'est envoyé (le motif et la date sont affichés dans la liste). Une fois votre serveur corrigé, cliquez sur Réactiver et corriger.
Les événements survenus pendant la désactivation ne sont pas rejoués. Si le statut d'un envoi vous manque, vous pouvez toujours l'interroger : statut de livraison par API.
Comment diagnostiquer un webhook en échec ?
Voir l'historique des livraisons (Paramètres → Webhooks) liste chaque tentative avec le code HTTP renvoyé, la latence, la prochaine tentative prévue et la dernière erreur. Le bouton Réessayer recrée la livraison immédiatement. Le contenu envoyé n'est pas conservé : corrélez avec vos propres journaux grâce à l'Event ID.
- Latence proche de 10 s : votre endpoint fait trop de travail avant de répondre (voir ci-dessous).
- 401 ou 403 : un pare-feu, une authentification ou une vérification de signature mal configurée bloque l'appel. Voir comment vérifier la signature d'un webhook Mailpro.
- 404 : l'URL enregistrée ne correspond plus à votre route (après une migration, par exemple).
- 5xx : une erreur dans votre code ; consultez vos journaux applicatifs à la date de la tentative.
Comment éviter les échecs ?
- Répondez vite, traitez ensuite : enregistrez l'événement, répondez 200, puis faites le traitement lourd en arrière-plan (file d'attente).
- Dédupliquez avec
X-Mailpro-Event-Id. - Ne renvoyez pas d'erreur pour un type d'événement que vous n'utilisez pas : répondez 2xx et ignorez-le.
- Surveillez le taux d'erreurs de votre endpoint pour réagir avant la désactivation.
// Exemple de principe (Node.js / Express)
app.post('/webhooks/mailpro', async (req, res) => {
const eventId = req.get('X-Mailpro-Event-Id');
if (await dejaTraite(eventId)) return res.sendStatus(200);
await fileAttente.ajouter(eventId, req.body); // traitement plus tard
res.sendStatus(200); // réponse immédiate, bien sous 10 s
});
Questions fréquentes
Puis-je relancer manuellement une livraison ?
Oui, le bouton Réessayer de l'historique des livraisons recrée la livraison immédiatement.
Les événements manqués seront-ils renvoyés après la réactivation ?
Non. Les événements survenus pendant la désactivation ne sont pas rejoués : interrogez le statut des envois concernés par API.
Webhook ou interrogation par API : que choisir ?
Le webhook vous prévient en temps réel, l'API vous permet de vérifier à la demande. Beaucoup d'intégrations utilisent les deux : voir webhook ou statut API, lequel choisir.
Pour démarrer : comment configurer un webhook et quels événements Mailpro envoie. Pour les SMS, le suivi se fait aussi dans le statut de livraison des SMS.
Mailpro et les webhooks
Au-delà des appels en échec : des webhooks qui réessaient
Le SMTP et l'API de Mailpro distribuent vos emails transactionnels et marketing avec des événements en temps réel, pour que votre app sache toujours ce qui s'est passé.