Résolution de problèmes des e-mails transactionnels

Cet article couvre les problèmes les plus courants avec les e-mails transactionnels de Flexmail — erreurs d'authentification, problèmes de délivrabilité et défaillances de l'API ou de SMTP — et ce qu'il faut faire pour les résoudre.

Erreurs d'authentification et de configuration

L'API renvoie une erreur 401 Unauthorized

Votre identifiant de compte ou votre jeton d'accès personnel est incorrect. Vérifiez les deux attentivement :

• Le nom d'utilisateur est votre identifiant de compte numérique, pas votre adresse e-mail.
• Le mot de passe est un jeton d'accès personnel créé dans Configuration > API > Jetons d'accès personnels, pas votre mot de passe de connexion Flexmail.
• Assurez-vous que le jeton a été copié intégralement, sans espaces ni sauts de ligne à la fin.
• En cas de doute, créez un nouveau jeton et réessayez.

La connexion SMTP échoue ou expire

Vérifiez les points suivants :

• Vous utilisez l'hôte submission.flexmail.eu, le port 587, avec STARTTLS.
• Votre serveur ou environnement d'hébergement autorise les connexions sortantes sur le port 587. Certains fournisseurs d'hébergement mutualisé bloquent ce port — contactez votre hébergeur pour le confirmer.
• Vos identifiants SMTP sont le nom d'utilisateur et le mot de passe fournis par Flexmail lors de l'activation de votre accès SMTP. Ces identifiants sont distincts de votre identifiant de compte et de votre jeton d'accès personnel, qui sont uniquement utilisés pour l'API HTTP.
• Votre adresse d'expéditeur est vérifiée dans Flexmail.

Adresse d'expéditeur non vérifiée

Si vous essayez d'envoyer depuis une adresse qui n'est pas vérifiée dans Flexmail, l'envoi sera rejeté. Accédez à Paramètres > Ajouter ou supprimer des expéditeurs, ajoutez l'adresse et cliquez sur le lien de vérification dans l'e-mail envoyé par Flexmail.

Problèmes de délivrabilité

Les e-mails arrivent dans le spam

Le placement dans le spam pour les e-mails transactionnels est presque toujours causé par l'une de ces trois choses :

• L'authentification des e-mails n'est pas configurée ou est incorrecte. Vérifiez que les enregistrements SPF, DKIM et DMARC sont en place pour votre domaine d'envoi. Même un seul enregistrement manquant ou mal configuré peut provoquer un placement dans le spam. Les instructions de configuration se trouvent dans la documentation de l'API sur email-api.flexmail.eu/documentation sous Authentification des e-mails.
• La réputation de l'expéditeur est faible. Si votre domaine ou votre IP a un historique de plaintes pour spam ou de taux de rebond élevés — sur n'importe quelle plateforme d'envoi, pas seulement Flexmail — les fournisseurs de messagerie peuvent acheminer vos e-mails vers le spam. Consultez « Comprendre la réputation de l'expéditeur » pour savoir comment évaluer et améliorer la réputation.
• Le contenu déclenche des filtres anti-spam. Certains modèles d'objet, un nombre excessif de liens ou des e-mails très chargés en images avec peu de texte peuvent déclencher des filtres anti-spam. Testez vos e-mails transactionnels avec un outil comme Mail-Tester (mail-tester.com) pour identifier les problèmes liés au contenu.

Les e-mails n'arrivent pas du tout

Si l'API renvoie une réponse de succès mais que l'e-mail n'arrive pas :

• Vérifiez vos événements webhook (si configurés) — un événement de rebond peu après l'envoi indique un échec de livraison.
• Vérifiez que l'adresse du destinataire existe et est orthographiée correctement.
• Demandez au destinataire de vérifier son dossier spam.
• Vérifiez si le domaine du destinataire a une politique DMARC stricte — sans DKIM correctement configuré, vos e-mails peuvent être silencieusement rejetés.
• Certains systèmes de messagerie d'entreprise rejettent les e-mails provenant d'expéditeurs nouveaux ou de faible réputation. Essayez d'envoyer à une adresse Gmail ou Outlook personnelle pour exclure un filtrage côté destinataire.

Taux de rebond élevé

Un taux de rebond élevé pour les e-mails transactionnels signifie généralement que vous envoyez à des adresses qui n'existent pas ou qui ne sont plus actives. Vérifiez votre processus de collecte des adresses :

• Validez-vous le format de l'adresse e-mail au point de saisie ?
• Envoyez-vous un e-mail de confirmation ou de vérification avant de faire confiance à une nouvelle adresse ?
• Supprimez-vous rapidement les adresses ayant subi un rebond définitif de votre système ?

Erreurs API et d'intégration

L'API renvoie une erreur 422 ou 400

Ces erreurs indiquent un problème avec votre requête : un champ obligatoire manquant, une valeur de paramètre invalide ou un corps de requête mal formé. Vérifiez le message d'erreur dans le corps de la réponse pour plus de détails. La documentation de l'API sur email-api.flexmail.eu/documentation liste tous les paramètres obligatoires et optionnels pour chaque point de terminaison.

L'API renvoie une erreur 429 Too Many Requests

Vous avez atteint une limite de débit. La documentation de l'API précise les limites de débit pour votre niveau d'abonnement. Ajoutez une logique de nouvelle tentative avec backoff exponentiel à votre intégration pour gérer cela de manière élégante.

Les variables du template ne sont pas remplacées

Si le texte des espaces réservés apparaît littéralement dans l'e-mail livré :

• Vérifiez que vous transmettez correctement les valeurs des variables dans la requête API. Consultez la section Templates de la documentation de l'API pour la structure exacte des paramètres.
• Vérifiez que la syntaxe des espaces réservés dans votre template correspond exactement à ce qu'attend l'API.
• Assurez-vous de référencer le bon ID de template dans votre appel API.

Les webhooks n'arrivent pas

Si votre point de terminaison webhook ne reçoit pas d'événements :

• Confirmez que votre point de terminaison est accessible publiquement via HTTPS.
• Vérifiez que votre point de terminaison renvoie rapidement une réponse 2xx — un point de terminaison lent ou qui ne répond pas amènera Flexmail à considérer la livraison comme échouée.
• Vérifiez les journaux de votre serveur pour les requêtes POST entrantes afin d'exclure un problème de routage ou de pare-feu.
• Vérifiez que l'URL de votre point de terminaison webhook est correctement enregistrée dans l'API.

Obtenir de l'aide

Si vous avez suivi les étapes ci-dessus et que le problème persiste, contactez l'équipe d'assistance Flexmail à l'adresse support@flexmail.eu. Incluez les informations suivantes dans votre message pour accélérer le diagnostic :

• L'ID du message d'un envoi échoué (depuis la réponse API ou vos journaux).
• L'adresse e-mail du destinataire avec laquelle vous avez effectué le test.
• Le message d'erreur ou le corps de la réponse de l'API, le cas échéant.
• Le résultat d'un outil de vérification de l'authentification des e-mails comme MXToolbox ou Mail-Tester.

Étapes suivantes

• Consultez « Premiers pas avec l'API transactionnelle » pour la séquence de configuration correcte.
• Consultez « Comprendre la réputation de l'expéditeur » pour savoir comment évaluer et protéger votre réputation d'envoi.
• Consultez la documentation de l'API sur email-api.flexmail.eu/documentation pour les codes d'erreur et les détails des limites de débit.