Skip to content

API Overview

Base URL

All API calls referenced in our documentation start with a base URL. Mailgun allows the ability to send and receive email in US, EU and AU regions. Be sure to use the appropriate base URL based on which region you have created for your domain.

It is also important to note that Mailgun uses URI versioning for our API endpoints, and some endpoints may have different versions than others. Please reference the version stated in the URL for each endpoint.

For domains created in our US region the base URL is:

https://api.mailgun.net/

For domains created in our EU region the base URL is:

https://api.eu.mailgun.net/

For domains created in our AU region (Contract only, Mailgun Send only) the base URL is:

https://api.au.mailgun.net/

Date Format

Mailgun APIs generally return dates in RFC-3339 format unless otherwise noted in the API docs. APIs that retrieve data from an email MIME return dates in RFC-2822 format. A handful of legacy APIs also use RFC-2822 format for historical reasons.

Warning!

Abbreviated time zones like (EST, CET, IST, HLC) may not result in the correct offset due to ambiguous nature. Use numerical offset (+0500) or GMT/UTC instead.

API Response Codes

All of Mailgun's HTTP response codes follow standard HTTP definitions.

CodeDescriptionTroubleshooting
400Bad RequestResponse typically contains a JSON "message" key with human-readable error details
401UnauthorizedInvalid or missing API key. Check that your API key is correct and properly formatted in the Authorization header
403ForbiddenValid credentials but access denied. Ensure you have permissions for the requested resource
404Not FoundResource not found. May be temporal due to eventually-consistent system. Missing JSON response usually indicates incorrect endpoint
429Rate LimitedRate limits exceeded. Retry as defined in response headers defined below. Contact support if limits need adjustment
500Internal ErrorMailgun server error. Retry with exponential backoff. Contact support if issue persists

Rate Limits

Mailgun returns a HTTP 429 in the response headers when a rate limit is reached in all cases EXCEPT the recipients rate limit of /messages, for which we return a HTTP 420. The response body will indicate request limit exceeded. Mailgun APIs include the following headers to indicate rate limiting state for the current API being called:

HeaderDescription
X-RateLimit-LimitTotal calls that can be made in each time window
X-RateLimit-RemainingCalls remaining in the given time window
X-RateLimit-ResetUnix milliseconds (UTC) until the limit resets. Used for back-off logic on a HTTP 429 response

By default, the following rate limits are in place for the referenced endpoints:

  • /messages

    • 80,000 API calls per 10 seconds, per account
  • /logs

    • 200,000 recipients per second, per account
  • /domains

    • 10 domains per second, per account
  • All other endpoints (unless otherwise noted)

    • 300 requests per second, per account

Mailgun Regions

Using a single account and billing plan, you can choose to provision new sending domains in the US, EU and AU regions. It is important to note that message data never leaves the region in which it is processed. Only a limited amount of account data is replicated globally, giving you a single account from which to manage domains in US, EU and AU.

Here are the specifics on the type of data that is replicated globally versus what is region-bound:

GlobalRegion-Bound (US / EU / AU)
  • Account Metadata
  • Users
  • Billing Details (invoices/plan information)
  • API Keys (with the exception of AU)
  • Sending domains and Metadata (e.g., SMTP credentials)
  • Messages (MIME content)
  • Event Logs
  • Metrics
  • Suppressions
  • Mailing Lists
  • Tags
  • Routes
  • IP Addresses

Below are the endpoints you will use for sending/receiving/tracking messages in our regions:

ServiceUSEUAU (Contract only)
REST APIapi.mailgun.netapi.eu.mailgun.netapi.au.mailgun.net
Outgoing SMTP Serversmtp.mailgun.orgsmtp.eu.mailgun.orgsmtp.au.mailgun.org
Inbound SMTP Server (Routes)mxa.mailgun.orgmxa.eu.mailgun.orgmxa.au.mailgun.org
Inbound SMTP Server (Routes)mxb.mailgun.orgmxb.eu.mailgun.orgmxb.au.mailgun.org
Open/Click Tracking Endpointmailgun.orgeu.mailgun.orgau.mailgun.org