We're experiencing difficulty. Our engineers are on it. Please check status.mailgun.com for real-time updates.

API Key Roles

Article Preview

    Overview

    Why does this feature matter? 
    API keys with roles assigned that correlate to the anticipated scope of the key's account needs is an essential component of 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.

    Role Description
    Admin

    In addition to all the permissions granted by the Developer role, the Admin role includes: 

    • Read/Write access to every Mailgun feature available via an API endpoint
    • Create and delete API keys
    • Create and delete SMTP credentials
    • Create, administer, and delete account users
    • Edit account and billing details

    Developer

    In addition to all the permissions granted by the Support role, the Developer role includes: 

    • Can read/write almost all data
      Edit webhooks
    • Edit routes
    • Edit Domain settings

    Support

    In addition to all the permissions granted by the Analyst role, the Support role includes:

    • Support users are restricted to what they can edit
      Can read most data
    • Edit suppressions
    • Edit mailing lists and members
    • Edit authorized recipients
    • Open and comment on support tickets

    Analyst

    • Access to read most data
    • Can only modify their own settings

     

    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.

    Endpoints Admin Analyst Developer Support
    Domains Read/Write Read Read/Write Read
    Messages Read/Write Read Read/Write Read
    Webhooks Read/Write Read Read/Write Read
    Events Read/Write Read Read/Write Read
    Tags Read/Write Read Read/Write Read
    Stats Read/Write Read Read/Write Read
    Unsubscribes(suppressions) Read/Write No Access Read/Write Read/Write
    Complaints (suppressions) Read/Write No Access Read/Write Read/Write
    Bounces (suppressions) Read/Write No Access Read/Write Read/Write
    Whitelist Read/Write Read Read/Write Read/Write
    Routes Read/Write Read Read/Write Read
    Mailing Lists Read/Write Read Read/Write Read/Write
    Templates Read/Write Read Read/Write Read
    IPs Read/Write Read Read/Write Read
    IP Pools Read/Write Read Read/Write Read
    Sub-Accounts Read/Write Read Read/Write Read
    Validations Read/Write Read Read/Write Read
    Secure Tracking Read/Write Read Read/Write Read

     

     

    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.
    ContentBlock-ProfileMenu.png
    1. Next, click the API Security option. Alternatively, you can use this direct link
    ContentBlock-AccountNav-APISecurity.png
    1. 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.
    ContentBlock-AccountSettings-APIKeys.png
    1. Finally, type a description and click the Create Key button in the pop-up modal to confirm creation of the new Mailgun API Key.
    Screenshot 2023-08-28 at 1.39.13 PM.png

     

    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.
    ContentBlock-ProfileMenu.png
    1. Next, click the API Security option. Alternatively, you can use this direct link
    ContentBlock-AccountNav-APISecurity.png
    1. The resulting page displays the Verifications Public Key, HTTP Webhook Signing Key, and most importantly for our present purpose, the Mailgun API Keys.
    ContentBlock.APISecurityPage.png

    Need Support?

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