Who this is for / when to use
This article is for developers, admins, or support teams troubleshooting Mailgun send failures, API responses, or delivery issues. Use it when an email request returns an HTTP status code (like 400, 403, 429) and an error message.
How to use this error code library
Mailgun errors are actionable when matched to the exact HTTP status code and error message returned by the API. Copy the full response (status + message), find it in the table below, and apply the listed solution. If the error mentions a parameter (like from, to, text, or html), fix the request payload first before checking domain/account settings.
Mailgun error codes and fixes
Use the tables below to match the Code + Error Message.
400 — Bad Request (missing/invalid parameters or malformed requests)
A 400 error means the request payload, parameters, headers, or formatting is invalid or incomplete. Fix the request fields first (sender, recipient, body, content-type, formatting limits), then retry.
Code | Error Message | Meaning | Solution |
400 | from parameter is missing | The sender’s email address is not provided. | Include the sender’s email in the |
400 | to parameter is missing | The receiver’s email address is not provided. | Include the receiver’s email in the |
400 | message parameter is missing | The email body is not provided. | Include the email body in the |
400 | ‘message’ parameter is not a file |
| Provide the message as a file. |
400 | Need at least one of ‘text’ or ‘html’ parameters specified | Neither plain text nor HTML is provided. | Include at least one of the |
400 | Only one parameters ‘html’ or ‘template’ is allowed | Both | Provide either |
400 | Send options (parameters starting with o:, h:, or v:) are limited to 16 kB total | Send options exceed the 16 kB limit. | Reduce |
400 | Too many recipients; max is 1000 | More than 1000 recipients are included. | Limit recipients to 1000 or fewer. |
400 | Header name must be pure ASCII: <header-name> | The header name includes non-ASCII characters. | Use only ASCII characters in header names. |
400 | <invalid-date> is not an RFC-2822 compliant date | The provided date format is invalid. | Format the date according to RFC-2822. |
400 | to parameter is not a valid address. please check documentation | Recipient email address format is invalid. | Correct the |
400 | from parameter is not a valid address. please check documentation | Sender email address format is invalid. | Correct the |
400 | cc parameter is not a valid address. please check documentation | CC email address format is invalid. | Correct the |
400 | bcc parameter is not a valid address. please check documentation | BCC email address format is invalid. | Correct the |
400 | Invalid request content type. Expecting ‘multipart/form-data’ but got ‘application/x-www-form-urlencoded’ | Request content type is incorrect. | Send the request as |
400 | malformed multipart/form-data request | Multipart formatting is incorrect. | Fix the |
400 | unable to parse request: invalid URL escape | URL contains invalid escape characters. | Correct the URL escape characters. |
400 | unable to parse request: unexpected EOF | Request ends unexpectedly. | Check for missing data or formatting issues in the request. |
400 | <time> invalid 24 hour time(value of ‘o:time-zone-localize’) | Time format is invalid. | Use a valid 24-hour time format for |
400 | <time> is not a valid time to send (value of ‘o:time-zone-localize’) | The scheduled send time is not valid. | Choose a different valid send time for |
400 | invalid delivery time format | Delivery time format is invalid. | Correct the delivery time format. |
400 | ‘recipient-variables’ parameter is not a valid JSON | Recipient variables JSON is malformed. | Fix the JSON format for |
400 | Domain example.com is not allowed to send: Sandbox subdomains are for test purposes only. Please add your own domain or add the address to authorized recipients in Account Settings. | Sandbox domains cannot send to unapproved recipients. | Use a non-sandbox domain or add the recipient to authorized recipients in Mailgun Account Settings. |
400 | Domain example.com is not allowed to send: Free accounts are for test purposes only. Please upgrade or add the address to authorized recipients in Account Settings. | Free accounts have sending restrictions. | Upgrade the account or add the recipient to authorized recipients in Mailgun Account Settings. |
400 | Domain example.com is not allowed to send: The domain is unverified and requires DNS configuration. Log in to your control panel to view required DNS records. | Domain is not verified / DNS not configured. | Verify the domain and configure required DNS records. |
400 | Domain example.com is not allowed to send: Please activate your Mailgun account. Check your inbox or log in to your control panel to resend the activation email. | Mailgun account is not activated. | Activate the Mailgun account using the activation email or resend activation from the control panel. |
400 | is not a valid secondary dkim domain name | Secondary DKIM domain is invalid. | Correct the secondary DKIM domain format. |
401 — Forbidden (permission issue)
A 401 Forbidden error means the credentials or user permissions do not allow the requested action. Confirm the API key/token is correct, active, and scoped appropriately for the domain and endpoint being used.
Code | Error Message | Meaning | Solution |
401 | Forbidden | The user does not have the necessary permissions. | Ensure the user/API key has the correct permissions for the request. |
403 — Forbidden (domain/IP limits or restrictions)
A 403 error means Mailgun is blocking the request due to policy, domain limitations, or IP sending restrictions. These are not fixed by changing message parameters; resolve the sending eligibility issue (batch permission, IP authorization) and then retry.
Code | Error Message | Meaning | Solution |
403 | Domain example is not allowed to send large batches yet | Domain is not authorized for large batches. | Request batch permission or send smaller batches. |
403 | Rejected: IP <id-address> can’t be used to send the message | Sending IP is not allowed. | Use an authorized IP address. |
404 — Not Found (invalid domain)
A 404 Domain not found error means the domain in the request does not exist in the Mailgun account or was referenced incorrectly. Confirm the exact domain name, spelling, and that it exists in the correct Mailgun account/environment.
Code | Error Message | Meaning | Solution |
404 | Domain not found: example.com | The specified domain does not exist. | Use a valid, existing domain. |
413 — Request Too Large
A 413 error means the request payload (attachments, body, or combined multipart content) exceeds Mailgun’s size limit for the endpoint. Reduce attachment sizes, remove unnecessary content, or send fewer/lighter files per request.
Code | Error Message | Meaning | Solution |
413 | request size exceeds 52.4MiB limit | Request payload exceeds the size limit. | Reduce request size to under 52.4 MiB. |
429 — Rate limits exceeded
A 429 error means Mailgun is throttling requests due to limits (requests, bytes, or recipients) for the domain/account. Wait until after the timestamp provided in the message and retry, or reduce throughput by sending smaller batches and spacing requests.
Code | Error Message | Meaning | Solution |
429 | Domain example.com is not allowed to send: request limit exceeded, try again after Mon, 20 Dec 2021 20:33:21 UTC | Request-rate limit exceeded. | Retry after the specified time. |
429 | Domain example.com is not allowed to send: bytes limit exceeded, try again after Mon, 20 Dec 2021 20:33:21 UTC | Byte limit exceeded. | Retry after the specified time. |
429 | Domain example.com is not allowed to send: recipient limit exceeded, try again after Mon, 20 Dec 2021 20:33:21 UTC | Recipient limit exceeded. | Retry after the specified time. |
500 — Internal Server Error
A 500 error indicates a server-side issue in Mailgun rather than a problem with your request payload. Retry after a short delay; if the error persists consistently for the same request, collect timestamps, request IDs (if available), and contact Mailgun support.
Code | Error Message | Meaning | Solution |
500 | Internal Server Error | There is a problem with the server. | Retry later or contact the server administrator/support. |
Common issues and fixes
These fixes resolve the most common root causes behind the errors listed above.
Emails fail with “from/to parameter is missing”
This happens when the request does not include required addressing fields. Ensure the request includes a valid from sender email and at least one valid recipient (to, and optionally cc/bcc) in proper email format. After updating the payload, resend the request and confirm the API response returns a 2xx success code.
Emails fail with “Need at least one of ‘text’ or ‘html’ parameters specified”
This happens when the message body is not provided in any supported format. Add text (plain text) and/or html (HTML body) to the request. If using templates, do not include html at the same time as template—choose one approach and resend the request.
Requests fail with “Expecting multipart/form-data”
This happens when the endpoint expects multipart/form-data but the request is sent as application/x-www-form-urlencoded. Update the request to use multipart/form-data, especially when sending attachments or file-based message content. After changing the content type, verify the multipart boundaries and fields are correctly constructed.
Sending blocked due to sandbox/free/unverified/activation domain errors
This happens when the sending domain or account is not eligible to send to the intended recipients. Use a verified, non-sandbox domain with required DNS records configured, ensure the Mailgun account is activated, and follow account rules for free/sandbox sending (authorized recipients). After eligibility is corrected, retry the send.
Glossary
fromparameter: Sender’s email address.toparameter: Receiver’s email address.ccparameter: Carbon copy email address.bccparameter: Blind carbon copy email address.text/htmlparameters: Plain text / HTML versions of the email body.templateparameter: A template reference used instead of raw HTML.o:/h:/v:parameters: Mailgun send options, headers, and variables.recipient-variables: JSON object containing recipient-specific variables.ASCII: American Standard Code for Information Interchange (character encoding).
RFC-2822: Internet Message Format date/header specification.
DNS: Domain Name System records used to verify and route domains.
DKIM: DomainKeys Identified Mail (email authentication mechanism).
MiB: Mebibyte, a unit of digital storage (binary-based).