Mailgun Error Codes Library

How to Use This Library

When Mailgun returns an error, match the code below and apply the recommended fix. Most issues resolve quickly by checking parameters, domain status, DNS verification, and account limits.

400 Errors (Bad Request)

A 400 error usually means something in the request is missing, invalid, or incorrectly formatted.

• from parameter is missing: Add a valid sender address in from.
• to parameter is missing: Add a valid recipient address in to.
• message parameter is missing: Provide an email body (or required message parameter).
• Need at least one of ‘text’ or ‘html’: Include a plain text or HTML body.
• Only one of ‘html’ or ‘template’ allowed: Use either HTML content or a template—not both.
• Too many recipients (max 1000): Reduce recipients to 1000 or fewer.
• Invalid address: Fix formatting for to, from, cc, or bcc.
• Invalid request type: Use the required content type (often multipart/form-data).
• Malformed multipart/form-data: Correct formatting issues in the payload or file uploads.
• Invalid delivery time: Use valid date/time formatting when scheduling.
• Sandbox domain limitation: Use a verified sending domain for production.
• Free account limitation: Upgrade if your plan limits production sending.
• Unverified domain: Verify DNS settings in Mailgun before sending.
• Inactive account: Complete activation/verification steps in Mailgun.

401 Error (Forbidden / Unauthorized)

A 401 generally points to authentication or permission issues.

• Confirm you’re using the correct API key (and that it hasn’t been rotated).
• Check the account role/permissions for the user making the request.
• Verify the request is being made against the correct region/endpoint for your Mailgun account, if applicable.

403 Errors (Restricted Action)

A 403 means the request is understood, but the action is blocked due to restrictions or policy.

• Large batch not allowed: Reduce batch size or request permission for higher volume.
• Rejected IP / unauthorized sending: Use an authorized sending IP or confirm domain/account restrictions.

404 Error (Domain Not Found)

This error usually means the domain you’re using doesn’t exist in your Mailgun account.

• Confirm the domain is added under Domains in Mailgun.
• Verify DNS records and domain status (especially if it was recently added).
• Check for typos in your domain string in the request.

413 Error (Request Too Large)

The request payload exceeded the maximum allowed size (often due to attachments).

• Reduce attachment size or number of files.
• Compress images/documents where possible.
• Send file links instead of large attachments when appropriate.

429 Errors (Rate Limits)

Rate limits can be triggered by request volume, total bytes, or recipients over a given time window.

• Request limit exceeded: Wait until the reset time, then retry.
• Bytes limit exceeded: Reduce payload size or frequency, then retry after reset.
• Recipient limit exceeded: Reduce recipients per send and use drip/batching.

500 Error (Internal Server Error)

A 500 error indicates a server-side issue at Mailgun.

• Retry after a short delay.
• If it persists, check Mailgun service status and contact support with request details.
• Log the full error response to help identify patterns.