Mailgun „401 Forbidden“: falscher API-Schlüssel oder EU/US-Region passt nicht

Was das bedeutet

Deine App hat die Mailgun-API aufgerufen und HTTP 401 Unauthorized bekommen. Der Antworttext ist oft nur das Wort Forbidden, was verwirrend ist. Laut der API-Referenz von Mailgun bedeutet 401, dass der API-Schlüssel fehlt oder ungültig ist, während 403 bedeutet, dass der Schlüssel gültig ist, der Zugriff auf diese Ressource aber verweigert wird. In der Praxis kommt ein 401 fast immer von einem der folgenden Probleme.

Warum das passiert

• Region passt nicht. Jede Sendedomain wird in der US- oder in der EU-Region angelegt. Eine in der EU angelegte Domain muss über https://api.eu.mailgun.net/ angesprochen werden, eine US-Domain über https://api.mailgun.net/. Der falsche Endpunkt schlägt auch mit einem gültigen Schlüssel fehl. Viele Bibliotheken und Plugins nutzen standardmäßig den US-Endpunkt.
• Falsche Art von Schlüssel. Mailgun hat mehrere Schlüssel: den privaten Mailgun API key (Kontoebene), domain sending keys (nur zum Senden, für eine Domain), den HTTP webhook signing key und den public verification key. Mit den letzten beiden kann man keine E-Mails senden.
• Ein Sending Key für eine andere Domain oder einen anderen Endpunkt. Ein Domain Sending Key funktioniert nur für /messages und /messages.mime auf der Domain, für die er erstellt wurde. Ein Aufruf von /v3/domains oder einer anderen Domain damit schlägt fehl.
• Fehlerhafte Basic Auth. Der Benutzername muss genau api lauten und das Passwort der Schlüssel sein. Mancher Code sendet den Schlüssel als Benutzernamen oder fügt Leerzeichen oder Anführungszeichen hinzu. Ältere Schlüssel beginnen mit key-, und dieses Präfix gehört zum Schlüssel.
• Gelöschter oder neu erzeugter Schlüssel. Schlüssel werden nur einmal angezeigt; vielleicht hat ein Teammitglied den Schlüssel rotiert, den du noch in .env hast.
• IP-Allowlist: Ist der API-Zugriff in den Sicherheitseinstellungen deines Kontos auf bestimmte IP-Adressen beschränkt, werden Aufrufe von einem neuen Server abgelehnt.

Ein 404 „Domain not found“ bedeutet meist, dass der Domainname in der URL falsch ist oder in der anderen Region existiert.

So prüfst du es

1. Öffne im Mailgun-Panel Send, Domains: Die Liste zeigt die Region jeder Domain (US oder EU).
2. Teste deinen Schlüssel mit curl und dem Endpunkt dieser Region:

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'

Kommt eine JSON-Antwort mit einer id und „Queued“ zurück, stimmen Schlüssel und Region, und das Problem liegt in der Konfiguration deiner App. Schlägt es fehl, probier den anderen Endpunkt: Funktioniert einer und der andere nicht, passt die Region nicht. Entferne .eu bei einer US-Domain.

So behebst du es

1. Stelle die Region in deiner Bibliothek ein. Beispiele:

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

Wähle in WordPress-SMTP-Plugins die passende Option Region. Dann:

1. Nutze den richtigen Schlüssel. Erstelle im Mailgun-Panel (API security / sending keys) einen neuen privaten API-Schlüssel oder einen Domain Sending Key und speichere ihn sofort; du wirst ihn nicht noch einmal sehen. Nutze den Sending Key nur zum Senden auf seiner eigenen Domain.
2. Achte auf versteckte Zeichen: keine Anführungszeichen im Wert, kein Leerzeichen und kein Zeilenumbruch am Ende durch Kopieren und Einfügen.
3. Aktualisiere die IP-Allowlist, falls du eine nutzt, mit der öffentlichen IP des Servers, der die API aufruft.
4. Bei SMTP ist der entsprechende Fehler ein 535-Authentifizierungsfehler. SMTP-Zugangsdaten gelten pro Domain und pro Region: Nutze smtp.eu.mailgun.org für EU-Domains und smtp.mailgun.org für US-Domains, mit dem SMTP-Login der Domain (zum Beispiel postmaster@mg.yourdomain.com). Nutzt du PHPMailer, siehe PHPMailer „Could not authenticate“.

Wird der Aufruf angenommen, die Nachricht aber abgelehnt, weil du noch die Sandbox-Domain nutzt, lies Mailgun-Sandbox: nur autorisierte Empfänger. Ist deine Domain noch nicht verifiziert, korrigiere zuerst ihr DNS mit Mailgun-Domain nicht verifiziert.

Prüfe, ob es behoben ist

Sende aus deiner App eine Nachricht an die einmalige Adresse auf der Startseite von Delivmail. Kommt sie an, funktioniert die Authentifizierung; der Bericht zeigt dir dann, ob SPF, DKIM und DMARC für deine Mailgun-Domain bestehen. Sende danach die mit 401 fehlgeschlagenen Nachrichten erneut und halte Region und Schlüssel an einer einzigen Stelle der Konfiguration, damit das nächste Deployment den Fehler nicht zurückbringt.