Mailgun "401 Forbidden": chiave API sbagliata o regione EU/US non corrispondente

Cosa significa

La tua applicazione ha chiamato l'API di Mailgun e ha ricevuto un HTTP 401 Unauthorized. Il corpo della risposta spesso è solo la parola Forbidden, il che confonde. Il riferimento API di Mailgun indica che 401 significa chiave API mancante o non valida, mentre 403 significa che la chiave è valida ma l'accesso a quella risorsa è negato. In pratica, un 401 deriva quasi sempre da uno dei problemi qui sotto.

Perché succede

• Regione non corrispondente. Ogni dominio di invio viene creato nella regione US o EU. Un dominio creato in EU deve essere chiamato su https://api.eu.mailgun.net/, un dominio US su https://api.mailgun.net/. Chiamare quello sbagliato fallisce anche con una chiave valida. Molte librerie e molti plugin usano per impostazione predefinita l'endpoint US.
• Tipo di chiave sbagliato. Mailgun ha diverse chiavi: la Mailgun API key privata (a livello di account), le domain sending keys (solo invio, per un dominio), la chiave di firma dei webhook HTTP e la chiave pubblica di verifica. Le ultime due non possono inviare email.
• Una sending key usata per un altro dominio o endpoint. Una domain sending key funziona solo per /messages e /messages.mime sul dominio per cui è stata creata. Usarla per chiamare /v3/domains o un altro dominio fallisce.
• Basic Auth errata. Il nome utente deve essere esattamente api e la password la chiave. Alcuni codici inviano la chiave come nome utente, oppure aggiungono spazi o virgolette. Le chiavi più vecchie iniziano con key-, e questo prefisso fa parte della chiave.
• Chiave eliminata o rigenerata. Le chiavi vengono mostrate una sola volta; un collega potrebbe aver ruotato la chiave che hai ancora nel .env.
• Lista di IP autorizzati: se l'accesso all'API è limitato ad alcuni indirizzi IP nelle impostazioni di sicurezza dell'account, le chiamate da un nuovo server vengono rifiutate.

Un 404 "Domain not found" di solito significa che il nome di dominio nell'URL è sbagliato o esiste nell'altra regione.

Come verificare

1. Nel pannello di Mailgun apri Send, Domains: l'elenco mostra la regione di ogni dominio (US o EU).
2. Prova la tua chiave con curl, usando l'endpoint di quella regione:

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'

Se ottieni una risposta JSON con un id e "Queued", chiave e regione sono corrette e il problema è nella configurazione della tua applicazione. Se fallisce, prova l'altro endpoint: se uno funziona e l'altro no, è un problema di regione. Togli .eu per un dominio US.

Come risolvere

1. Imposta la regione nella tua libreria. Esempi:

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

Nei plugin SMTP per WordPress, scegli l'opzione Region corrispondente. Poi:

1. Usa la chiave giusta. Crea una nuova chiave API privata o una domain sending key nel pannello di Mailgun (API security / sending keys) e salvala subito: non la vedrai più. Usa la sending key solo per inviare dal suo dominio.
2. Cerca caratteri nascosti: niente virgolette dentro il valore, niente spazio finale o a capo dovuti al copia e incolla.
3. Aggiorna la lista di IP autorizzati se ne usi una, con l'IP pubblico del server che chiama l'API.
4. Per SMTP, l'errore equivalente è un fallimento di autenticazione 535. Le credenziali SMTP sono per dominio e per regione: usa smtp.eu.mailgun.org per i domini EU e smtp.mailgun.org per quelli US, con il login SMTP del dominio (per esempio postmaster@mg.yourdomain.com). Se usi PHPMailer, consulta PHPMailer "Could not authenticate".

Se la chiamata viene accettata ma il messaggio è rifiutato perché usi ancora il dominio sandbox, leggi sandbox di Mailgun: solo destinatari autorizzati. Se il tuo dominio non è ancora verificato, sistema prima il suo DNS con dominio Mailgun non verificato.

Verifica che sia risolto

Invia un messaggio dalla tua applicazione all'indirizzo unico nella home page di Delivmail. Se arriva, l'autenticazione funziona; il report ti dice poi se SPF, DKIM e DMARC sono superati per il tuo dominio Mailgun. Poi invia di nuovo i messaggi falliti con 401 e tieni regione e chiave in un unico punto della configurazione, così il prossimo deploy non riporterà l'errore.