API Key Management and Security
Email API keys allow secure access to email services and data. They enable sending emails, managing contacts, and integrating email functionalities into applications. Proper management of these keys ensures smooth operation, protects against unauthorized access, and maintains the security of sensitive information.
Managing Role-Based Access Control (RBAC) API Keys
Roles Based Access Control (RBAC) API Keys empower admin users to generate API keys utilizing predefined roles that dictate the access level of each key.
Note:
- Assigned roles cannot be updated. You will need to create a new key. Be sure to save the key in a safe place, as you will only be able to see it once when you create it.
- Role-Based Access Control is only available on specific plans. See our Pricing page for more details https://www.mailgun.com/pricing/
- Only Admins have read/write access. All other roles will have read access.
API Permissions
During the API key creation process, you will be able to select a predefined role. This role assigns certain access levels to various public API endpoints. Read and write privileges are based on the role assigned to the API key.
| Permission Type | Description |
|---|---|
| No Access | Will have no access to certain public API endpoints. |
| Read: | Allows the API key to access GET endpoints within the selected permission. |
| Read/Write: | Allows the API Key to access GET,PATCH,PUT,DELETE, and POST endpoints within the selected permission. |
RBAC API Key Permissions Based on Role
The assigned roles below determines the API key’s permissions (or access and rights) per public API endpoint.
| 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 (suppressions) | 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 |
| Custom Message Limit | Read/Write | Read | Read | Read |
| Credentials | Read/Write | No Access | Read | No Access |
| Keys | Read/Write | No Access | Read | No Access |
| IP Allowlist | Read/Write | Read | Read/Write | Read |
| Account Management | Read/Write | Read | Read/Write | Read |
| Users on an account | Read | No Access | No Access | No Access |
| Another user's details on an account | Read | No Access | No Access | No Access |
| Own user details | Read | Read | Read | Read |
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.
