Overview

Authentication is required any time you wish to relay messages through our platform. When using our API, you need to use one of your account's API keys (either an Account API Key or a Domain Sending Key).

For our SMTP server, you need to use your domain's SMTP credentials.

API Keys

Mailgun Account API Keys

Account API Keys provide access to our numerous API endpoints that allow you to view and modify many aspects of your account and domains. In other words, you can programmatically perform nearly all the same tasks using the Mailgun APIs that otherwise would be performed within the Mailgun Control Panel.

Mailgun allows for the creation and use of multiple API Keys on the account. Multiple API Keys are useful for several scenarios such as the two listed below.

• Segmenting usage by providing a unique key for each of your organization's applications, environments, teams, or departments. When used for this purpose and configured correctly, any problem associated with a single API Key would only impact one application, one environment, one team, or one department instead of all applications, environments, teams, or departments.
• Periodic rotation of the keys. While an existing API Key remains in use, a new API Key can be created and then used to replace the existing API Key at a pace and urgency that suits your schedule.

Important Note!

The Mailgun API Key can be seen only once: within a pop-up modal after the key's creation. As such, in addition to configuring the Mailgun API Key in your sending application(s), store the Mailgun API Key in a secure location (such as your organization's credential/password manager) for future reference.

Consequently, if you lose the Mailgun API Key, Mailgun will not be able to view and/or disclose the Mailgun API Key at a later date. The only solution for this situation is to create a new Mailgun API Key, configure your sending application(s) with the new Mailgun API Key, and store the new Mailgun API Key in a secure location for future reference.

Rather watch a video? The video below will begin at the section demonstrating the creation of an API key.

To create a new Mailgun API Key:

1. In the top-right corner of the Mailgun Control Panel, click your Profile Menu to expand the drop-down list of options.

2. Next, click the API Security option. Alternatively, you can use this direct link. 

3. The resulting page displays the Verifications Public Key, HTTP Webhook Signing Key, and most importantly for our present purpose, the Mailgun API Keys. To create the new key, click the Add new key button.
   
4. Finally, type a description, choose a role, and click the Create Key button in the pop-up modal to confirm creation of the new Mailgun API Key.
   1. Note: Accounts using the Free or Basic plans will not have the ability to choose a role other than Admin for the API key.

Domain Sending Keys

Domain Sending Keys are API keys that only allow sending messages using a POST call via our /messages and /messages.mime endpoints for the domain in which they are created for. We'll show you how to do this below:

1. First, log in to the Mailgun Control Panel (if you have not already done so).
2. Then, within the left-hand navigation pane, click the Send product and then click the Sending option to expand its list of sub-options.
   
   
3. Next, click the Domain settings suboption, and then click on the Sending API keys tab.
   
   
4. Click the Add sending key button.
5. In the pop-up modal, enter a suitable description (such as the name of the application or client you're creating the key for) before finally clicking the Create sending key button.
   
   
6. Copy your sending 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.
   

Note: Once you add a new Domain Sending Key, they are ready to be used immediately, 
and do not affect usage of your primary API key.

HTTP Webhook Signing Key

Mailgun uses the account's HTTP Webhook Signing Key to sign all HTTP payloads sent to the webhook endpoints (if any) configured on your account.

1. First, log in to the Mailgun Control Panel (if you have not already done so).
2. Then, in the top-right corner of the Mailgun Control Panel, click your Profile Menu to expand the drop-down list of options.
   
3. Next, click the API Security option. Alternatively, use this direct link.
   

   

4. Now, for the existing key in the HTTP webhook signing key section, click the refresh icon.
   
   
5. Finally, click the Reset Key button in the pop-up modal to confirm deletion of the existing HTTP webhook signing key. This will automatically generate a new HTTP webhook signing key as well.
   
   

SMTP Credentials

Your SMTP credentials are different for each domain you add. You can find any currently added users, and add more, by clicking through to your domain settings. We'll show you how to do this below:

1. First, log in to the Mailgun Control Panel (if you have not already done so).
2. Then, within the left-hand navigation pane, click the Send product and then click the Sending option to expand its list of suboptions.
   
   
3. Next, click the Domain settings suboption, and then click on the SMTP credentials tab.
   
   
4. Ensure that the domain for which you wish to reset the SMTP credentials is displayed within the Domain drop-down list towards the upper-right portion of the page.
   
5. To update the password, click the Reset password button.
6. Confirm your password reset by clicking the Reset Password button in the pop-up modal.
   
7. NOTE: The new SMTP password will be available to copy within a dark-gray notification window that appears in the bottom-right portion of the Control Panel. Copy and save this password in your application and in a secure password manager, as it will not be displayed again. 
   

Want to create SMTP credentials using the Domain API? Need to shorten or otherwise customize your SMTP password?  Check out this article!

SMTP Ports & Encryption Protocols

Our servers listen on ports 25, 465 (SSL/TLS), 587 (STARTTLS), and 2525.

A few things to note when selecting a port:

• Some ISPs block or throttle SMTP port 25. We recommend using port 587 instead.
• Google Compute Engine allows port 2525 for SMTP submission.
• Mailgun IPs change frequently, we do not recommend setting up firewall restrictions against our IP addresses.
• See our SMTP documentation in the Users Manual to learn how to configure the most popular SMTP software and email clients to work with Mailgun.

For a more detailed explanation of ports check out our blog post.

Need Support?

Our Support Team here at Sinch Mailgun is happy to help! Reach out to us in the Support page of your Mailgun Control Panel, and we'll be with you shortly!