Overview

Why does this feature matter? 
Assigning API keys a role that corresponds to their necessary - and only necessary - scope of actions is an essential component of overall account security.

Mailgun API keys are RESTful API keys that have access to control many functions of your Mailgun account: sending messages, managing domains, checking suppressions, monitoring analytics, and more.

API Key Roles, or what could also be termed API Key Role-Based Access Control (RBAC) or RBAC API Keys, determine what sort of permissions a given API key - and thus, any and all user(s) of that API key - has upon your Mailgun account.

For further technical details, be sure to check out our Mailgun User Manual!

Important Note: 
RBAC API Keys are a feature available to the following plans:
• Foundation
• Scale
• Contract
• Enterprise

Understanding API key roles

Note: 
Only an account user with the admin role (RBAC Account Users) can create API keys, and thus, assign roles to newly created API keys.

Note: 
Once a role is assigned to an API key, the role cannot be updated. Instead, a new key would need to be created and the intended role assigned.

There are currently four roles available for API keys, and every API key that accesses your Mailgun account must have one of these API key roles assigned to that key:

1. Admin
2. Developer
3. Support
4. Analyst

Depending on the Mailgun feature, a role will have access to view and/or modify the feature in question. Read (i.e. view) and write (i.e. create, edit/modify/update, delete) are technical terms that correspond to various HTTP API verbs such as GET and POST. For further technical details, please reference our Mailgun User Manual.

Table of permissions: Summarized by role

To better understand which role is best for a given API key, the below table summarizes briefly the permissions by role. For permissions detailed comprehensively by API endpoint, see the section below.

Table of permissions: Detailed by API endpoint

To fully understand which role is best for a given API key, the below table (also found in our our Mailgun User Manual) describes comprehensively the permissions available to every API endpoint. For permissions summarized briefly by role, see the section above.

* Custom Message Limit 

The Custom Message Limit imposes a hard limit on how many messages your account can send during a calendar month. The primary account holder will receive an e-mail notification when 50% and 75% of the limit has been crossed. After the limit has been reached, the account will be disabled until the beginning of the following month, or until it has been re-enabled in the dashboard or by modifying the message limit via API. 

As for subaccount custom message limits, only the account user roles of Admin, Developer, and Billing can configure such limits via the Subaccount Custom Sending Limit API endpoint or within the Create/Edit Subaccounts page of the Control Panel.

Managing API keys

Creating API keys

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.

Viewing API Keys

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.

To view the account's Mailgun API Keys (or more specifically their associated API Key IDs, Descriptions, and Created Dates):

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.
   

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!