Mailgun "401 Forbidden": clave de API incorrecta o región UE/EE. UU. equivocada

Qué significa

Tu aplicación ha llamado a la API de Mailgun y ha recibido un HTTP 401 Unauthorized. A menudo el cuerpo de la respuesta es solo la palabra Forbidden, lo que confunde. La referencia de la API de Mailgun dice que 401 significa que la clave de API falta o no es válida, mientras que 403 significa que la clave es válida pero se deniega el acceso a ese recurso. En la práctica, un 401 casi siempre se debe a uno de los problemas siguientes.

Por qué ocurre

• Región equivocada. Cada dominio de envío se crea en la región de EE. UU. o en la de la UE. A un dominio creado en la UE hay que llamarlo en https://api.eu.mailgun.net/, y a uno de EE. UU. en https://api.mailgun.net/. Llamar al equivocado falla incluso con una clave correcta. Muchas librerías y plugins usan por defecto el endpoint de EE. UU.
• Tipo de clave equivocado. Mailgun tiene varias claves: la Mailgun API key privada (a nivel de cuenta), las domain sending keys (solo para enviar, para un dominio), la clave de firma de webhooks HTTP y la clave pública de verificación. Las dos últimas no pueden enviar emails.
• Una clave de envío usada para otro dominio u otro endpoint. Una domain sending key solo funciona para /messages y /messages.mime en el dominio para el que se creó. Llamar con ella a /v3/domains o a otro dominio falla.
• Basic Auth mal configurada. El usuario debe ser exactamente api y la contraseña, la clave. Hay código que envía la clave como usuario, o que añade espacios o comillas. Las claves antiguas empiezan por key-, y ese prefijo forma parte de la clave.
• Clave eliminada o regenerada. Las claves solo se muestran una vez; puede que un compañero haya rotado la clave que tú sigues teniendo en .env.
• Lista de IP permitidas: si el acceso a la API está restringido a ciertas direcciones IP en la configuración de seguridad de tu cuenta, se rechazan las llamadas desde un servidor nuevo.

Un 404 "Domain not found" suele significar que el nombre de dominio de la URL es incorrecto o que existe en la otra región.

Cómo comprobarlo

1. En el panel de Mailgun, abre Send, Domains: la lista muestra la región de cada dominio (US o EU).
2. Prueba tu clave con curl, usando el endpoint de esa región:

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 devuelve una respuesta JSON con un id y "Queued", la clave y la región son correctas y el problema está en la configuración de tu aplicación. Si falla, prueba el otro endpoint: si uno funciona y el otro no, es un problema de región. Quita .eu para un dominio de EE. UU.

Cómo solucionarlo

1. Configura la región en tu librería. Ejemplos:

// 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

En los plugins SMTP de WordPress, elige la opción Region correspondiente. Después:

1. Usa la clave correcta. Crea una nueva clave de API privada o una domain sending key en el panel de Mailgun (API security / sending keys) y guárdala de inmediato; no volverás a verla. Usa la clave de envío solo para enviar desde su propio dominio.
2. Busca caracteres ocultos: sin comillas dentro del valor, sin espacios ni saltos de línea al final procedentes de copiar y pegar.
3. Actualiza la lista de IP permitidas si usas una, con la IP pública del servidor que llama a la API.
4. Para SMTP, el error equivalente es un fallo de autenticación 535. Las credenciales SMTP son por dominio y por región: usa smtp.eu.mailgun.org para los dominios de la UE y smtp.mailgun.org para los de EE. UU., con el usuario SMTP del dominio (por ejemplo postmaster@mg.yourdomain.com). Si usas PHPMailer, consulta PHPMailer "Could not authenticate".

Si la llamada se acepta pero el mensaje se rechaza porque sigues usando el dominio sandbox, lee sandbox de Mailgun: solo destinatarios autorizados. Si tu dominio aún no está verificado, corrige primero su DNS con dominio de Mailgun no verificado.

Comprueba que está solucionado

Envía un mensaje desde tu aplicación a la dirección única de la página de inicio de Delivmail. Si llega, la autenticación funciona; el informe te dirá entonces si SPF, DKIM y DMARC se superan para tu dominio de Mailgun. Después reenvía los mensajes que fallaron con 401 y guarda la región y la clave en un único lugar de configuración para que el próximo despliegue no vuelva a provocar el error.