Mailgun « 401 Forbidden » : mauvaise clé API ou confusion entre région EU et US

Ce que ça veut dire

Votre application a appelé l'API Mailgun et a reçu un HTTP 401 Unauthorized. Le corps de la réponse se limite souvent au mot Forbidden, ce qui prête à confusion. La référence de l'API Mailgun indique qu'un 401 signifie que la clé API est absente ou invalide, alors qu'un 403 signifie que la clé est valide mais que l'accès à cette ressource est refusé. En pratique, un 401 vient presque toujours de l'un des problèmes ci-dessous.

Pourquoi cela arrive

• Région qui ne correspond pas. Chaque domaine d'envoi est créé dans la région US ou dans la région EU. Un domaine créé dans l'EU doit être appelé sur https://api.eu.mailgun.net/, un domaine US sur https://api.mailgun.net/. Appeler le mauvais échoue même avec une bonne clé. Beaucoup de bibliothèques et de plugins utilisent par défaut le point d'accès US.
• Mauvais type de clé. Mailgun a plusieurs clés : la Mailgun API key privée (au niveau du compte), les domain sending keys (envoi uniquement, pour un seul domaine), la clé de signature des webhooks HTTP et la clé publique de vérification. Les deux dernières ne permettent pas d'envoyer d'emails.
• Une clé d'envoi utilisée pour un autre domaine ou un autre point d'accès. Une domain sending key ne fonctionne que pour /messages et /messages.mime sur le domaine pour lequel elle a été créée. Appeler /v3/domains ou un autre domaine avec elle échoue.
• Mauvaise authentification Basic Auth. Le nom d'utilisateur doit être exactement api et le mot de passe la clé. Certains codes envoient la clé comme nom d'utilisateur, ou ajoutent des espaces ou des guillemets. Les anciennes clés commencent par key-, et ce préfixe fait partie de la clé.
• Clé supprimée ou régénérée. Les clés ne s'affichent qu'une fois ; un collègue a peut-être renouvelé la clé que vous avez encore dans .env.
• Liste d'IP autorisées : si l'accès à l'API est limité à certaines adresses IP dans les réglages de sécurité du compte, les appels d'un nouveau serveur sont refusés.

Un 404 « Domain not found » signifie généralement que le nom de domaine dans l'URL est faux ou qu'il existe dans l'autre région.

Comment vérifier

1. Dans le panneau Mailgun, ouvrez Send, Domains : la liste indique la région de chaque domaine (US ou EU).
2. Testez votre clé avec curl, en utilisant le point d'accès de cette région :

curl -s --user 'api:YOUR_API_KEY' \
  https://api.eu.mailgun.net/v3/mg.yourdomain.com/messages \
  -F from='Test <hello@mg.yourdomain.com>' \
  -F to='you@example.com' \
  -F subject='Mailgun test' \
  -F text='Hello'

Si vous obtenez une réponse JSON avec un id et « Queued », la clé et la région sont bonnes et le problème vient de la configuration de votre application. En cas d'échec, essayez l'autre point d'accès : si l'un fonctionne et pas l'autre, c'est un problème de région. Retirez .eu pour un domaine US.

Comment corriger

1. Indiquez la région dans votre bibliothèque. Exemples :

// mailgun.js (Node)
const mg = new Mailgun(FormData).client({
  username: 'api',
  key: process.env.MAILGUN_API_KEY,
  url: 'https://api.eu.mailgun.net', // only for EU domains
});

# Laravel .env
MAILGUN_DOMAIN=mg.yourdomain.com
MAILGUN_SECRET=your-private-or-sending-key
MAILGUN_ENDPOINT=api.eu.mailgun.net

# Symfony Mailer
MAILER_DSN=mailgun+api://KEY:mg.yourdomain.com@default?region=eu

Dans les plugins SMTP de WordPress, choisissez l'option Region correspondante. Ensuite :

1. Utilisez la bonne clé. Créez une nouvelle clé API privée ou une domain sending key dans le panneau Mailgun (API security / sending keys) et enregistrez-la tout de suite : vous ne la reverrez plus. N'utilisez la clé d'envoi que pour envoyer sur son propre domaine.
2. Traquez les caractères invisibles : pas de guillemets dans la valeur, pas d'espace ni de retour à la ligne final issu d'un copier-coller.
3. Mettez à jour la liste d'IP autorisées si vous en utilisez une, avec l'IP publique du serveur qui appelle l'API.
4. En SMTP, l'erreur équivalente est un échec d'authentification 535. Les identifiants SMTP sont propres à chaque domaine et à chaque région : utilisez smtp.eu.mailgun.org pour les domaines EU et smtp.mailgun.org pour les domaines US, avec l'identifiant SMTP du domaine (par exemple postmaster@mg.yourdomain.com). Si vous utilisez PHPMailer, voir PHPMailer « Could not authenticate ».

Si l'appel est accepté mais que le message est refusé parce que vous utilisez encore le domaine sandbox, lisez sandbox Mailgun : destinataires autorisés uniquement. Si votre domaine n'est pas encore vérifié, corrigez d'abord son DNS avec domaine Mailgun non vérifié.

Vérifier que c'est corrigé

Envoyez un message depuis votre application à l'adresse unique de la page d'accueil de Delivmail. S'il arrive, l'authentification fonctionne ; le rapport vous dit alors si SPF, DKIM et DMARC passent pour votre domaine Mailgun. Renvoyez ensuite les messages qui avaient échoué en 401, et regroupez la région et la clé à un seul endroit de votre configuration pour que le prochain déploiement ne ramène pas l'erreur.