Authentication

Authentication to the Mailgun API is done by providing an Authorization header using HTTP Basic Auth:

  • Username: api
  • Password: Your API key

Mailgun provides two types of API keys for authenticating against the API:

Primary account API key

When you sign up for Mailgun, a primary account API key is generated. This key allows you to perform all CRUD operations via our various API endpoints and for any of your sending domains. To view your primary account API key:

  1. Go to the Mailgun Dashboard
  2. Click on Account settings located on the upper right
  3. Click API Security

Domain Sending Keys

Domain Sending Keys are API keys that only allow sending messages via a POST call on /messages and /messages.mime endpoints for the domain in which they are created for. To create a sending API key:

  1. Go to the Mailgun Dashboard
  2. Click the Sending tabon the left-hand side of the Mailgun dashboard
  3. Click the Domains tab and select the domain in which you wish to add a sending key to
  4. Click the Domain Settings and navigate to the Sending API keys tab
  5. Click on Add Sending Key

Give your key a suitable description (such as the name of the application or client you are creating the key for) and click Create Sending Key

Copy your API key and keep it in a safe place. For security purposes, we will not be able to show you the key again. If you lose your key, you will need to create a new key.

Here is how you use basic HTTP auth with curl:

Copy
Copied
curl --user 'api:YOUR_API_KEY'
Warning!

Important Reminder** to keep your API safe and secure

Date Format

Mailgun returns JSON for all API calls. JSON does not have a built-in date type; dates are passed as strings encoded according to RFC 2822#page-14. This format is native to JavaScript and is also supported by most programming languages out of the box:

Copy
Copied
'Thu, 13 Oct 2011 18:02:00 +0000'
Warning!

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

Mailgun Regions

Using a single account and billing plan, you can choose to provision new sending domains in the EU environment. 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 both the US and the EU.

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

Global Region-Bound (US / EU)
Account Information, User Accounts, Billing Details (invoices/plan information), API Keys, Domain Names Domain Metadata (e.g., SMTP credentials), Messages, Event Logs, Suppressions, Mailing Lists, Tags, Statistics, Routes, IP Addresses

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

Service US Endpoint EU Endpoint
REST API api.mailgun.net api.eu.mailgun.net
Outgoing SMTP Server smtp.mailgun.org smtp.eu.mailgun.org
Inbound SMTP Server (Routes) mxa.mailgun.org mxa.eu.mailgun.org
Inbound SMTP Server (Routes) mxb.mailgun.org mxb.eu.mailgun.org
Open/Click Tracking Endpoint
mailgun.org eu.mailgun.org