Skip to main content
Error response shape: 
{
  "error": "message"
}
Common status codes:
  • 400 invalid request
  • 401 missing/invalid bearer token
  • 403 missing scope
  • 404 resource not found
  • 409 idempotency conflict
  • 422 plan/validation limits
  • 429 rate limited
  • 500 provider/internal failure
Use idempotency keys and exponential backoff for retryable failures.

​
Inbound webhook statuses

When Mailgun forwards inbound mail to /webhooks/mailgun/inbound:
  • 200 with {"ok": true}: inbound accepted and saved.
  • 200 with {"ok": true, "duplicate": true}: duplicate delivery ignored.
  • 202 with {"ok": true, "ignored": true}: recipient inbox not found.
  • 401: signature verification failed (MAILGUN_WEBHOOK_SIGNING_KEY mismatch).