Dépannage

Commencez par le code d’erreur : chaque erreur de l’API contient code et docs_url, et Codes d’erreur les explique un par un. L’Historique affiche chaque message accepté avec sa chronologie, la réponse du fournisseur et le contenu généré.

La requête échoue

403 origin_not_allowed – Ajoutez le domaine de votre site dans Sécurité → Sites autorisés (et localhost pour le développement). Vérifiez l’hôte exact, www. compris. Avec details.reason: "no_origin", la requête n’avait aucun Origin (application native, script serveur) : activez Autoriser les applications mobiles pour les applications, utilisez une clé privée sur les serveurs. Voir Domaines autorisés.

403 private_key_in_browser – Une clé privée a été utilisée depuis une page web. Utilisez la clé publique dans le navigateur et gardez la clé privée sur votre serveur. Voir Clés.

403 captcha_required / captcha_failed – Le modèle exige Turnstile. Affichez le widget dans le formulaire ou transmettez turnstileToken ; réinitialisez le widget après chaque tentative, car les jetons sont à usage unique. captcha_failed avec hostname_mismatch signifie que le widget a été résolu sur un nom d’hôte qui n’est pas l’origine de la requête – ajoutez tous les noms d’hôte de votre site à votre widget Turnstile. Voir Turnstile.

403 captcha_not_configured – Le modèle exige le CAPTCHA, mais votre organisation n’a pas ajouté ses propres clés Turnstile. Créez un widget gratuit dans Cloudflare et collez sa clé de site et sa clé secrète dans Sécurité → Protection contre les bots (Turnstile), ou désactivez le CAPTCHA sur le modèle.

422 invalid_template_params – Regardez details.issues : chaque problème indique le param et la règle. Causes fréquentes : un champ obligatoire est vide, un paramètre email a reçu un nom, un paramètre number a reçu "12 pcs", un paramètre list a reçu une chaîne qui n’est pas du JSON.

403 dynamic_recipient_not_allowed – Le champ To/CC/BCC du modèle utilise un paramètre. Utilisez une réponse automatique pour les confirmations, ou activez Autoriser un destinataire dynamique dans Paramètres → Protection du modèle.

429 rate_limited – Vous avez dépassé la limite du forfait, de l’IP ou de la clé. Le SDK a déjà attendu et réessayé. Pour les envois en masse depuis un serveur, utilisez les envois groupés.

Erreur CORS dans la console du navigateur – Généralement une autre erreur déguisée : la requête a été bloquée par une Content-Security-Policy (connect-src), un bloqueur de publicités, ou est partie vers un mauvais apiUrl. L’API Frontmail envoie des en-têtes CORS pour toutes les origines ; l’accès est contrôlé par les domaines autorisés.

La requête réussit, mais aucun e-mail n’arrive

1. Trouvez le message dans l’Historique.
   • held – vous n’avez plus de crédits. Achetez un pack (Acheter des crédits) ou attendez le renouvellement ; il sera envoyé automatiquement. Il figure aussi dans E-mails retenus. Voir File d’attente des e-mails retenus.
   • held_service_error – les identifiants de votre service ne fonctionnent plus. Ouvrez Services d’envoi, réparez ou reconnectez le service ; les messages retenus sont ensuite envoyés automatiquement.
   • failed – ouvrez le message : l’erreur du fournisseur est affichée dans la chronologie. Les causes typiques sont un domaine d’expéditeur non vérifié ou un destinataire invalide.
   • sent – le fournisseur l’a accepté. Continuez ci-dessous.
2. Vérifiez les spams. S’il s’y trouve, configurez SPF, DKIM et DMARC pour votre domaine d’expédition comme décrit dans le guide de votre fournisseur, et utilisez une adresse d’expéditeur sur ce domaine (pas une adresse @gmail.com via un fournisseur transactionnel).
3. Vérifiez la liste de suppression. Les envois vers des adresses bloquées échouent avec 451, mais si vous avez retiré l’adresse de la liste après un rebond, la boîte peut toujours ne pas exister.
4. Configurez les webhooks pour voir les événements delivered / bounced au lieu de deviner.

Le service repasse sans cesse en panne

• Gmail : Google révoque les jetons d’actualisation quand le mot de passe change, quand l’utilisateur retire l’accès de l’application ou après 6 mois sans utilisation. Reconnectez le service.
• Fournisseurs par API : la clé a été renouvelée ou ses autorisations réduites. Créez une clé avec l’autorisation d’envoi (send) et mettez à jour le service.
• SMTP : le mot de passe de la boîte a changé, ou le fournisseur exige un mot de passe d’application quand la 2FA est activée.

Ajoutez un service de secours pour qu’un service en panne ne bloque pas vos formulaires pendant que vous le réparez.

Les e-mails s’affichent mal

• Styles absents dans Gmail ou Outlook → activez Intégrer le CSS en ligne à l’enregistrement dans les Paramètres du modèle.
• Texte coupé avec « Afficher l’intégralité du message » → l’e-mail dépasse ~100 ko ; retirez les images intégrées ou les styles volumineux.
• <b> littéral dans l’e-mail → la valeur a été échappée. Utilisez un paramètre html si vous avez vraiment besoin de balisage (voir l’échappement).
• Dates dans la mauvaise langue ou le mauvais fuseau horaire → définissez la langue du modèle et le fuseau horaire de votre organisation, ou passez timeZone= à formatDate.

Toujours bloqué ?

Écrivez à support@frontmail.dev en indiquant le message_id (ou le code et l’heure de l’erreur). N’incluez jamais votre clé privée.