API Keys
Manage and generate API keys to enable external applications to securely interact with the system. These keys provide controlled access to specific functionalities, ensuring secure integration with third-party tools or services.
Navigate to Settings → API Keys to manage API access.
Page Layout
The API Keys page has two tabs:
| Tab | Purpose |
|---|---|
| API Keys | Create and manage API tokens |
| API Roles | Define permission sets that can be assigned to API keys |
API Keys Tab
Viewing API Keys
The API Keys list displays all generated tokens:
| Column | Description |
|---|---|
| API Key | The token value (used for authentication) |
| Description | Human-readable description of what this key is used for |
| API Name | The API role assigned to this key |
| Owner | User who created the key (name and email) |
| Allowed IPs | IP restrictions if configured |
| Last Accessed | When the key was last used for an API call |
| Status | Green checkmark indicates active |
| Actions | Toggle status, Edit, Delete |
Page Controls
- Create an API Key - Generate a new API token
- Show entries - Control how many keys are displayed per page
- Search - Filter keys by any column value
Creating an API Key
- Click Create an API Key
- The system generates a new API token and opens the settings modal
- Configure the key settings (see below)
- Click Update to save
The generated API key is displayed in the list and can be viewed or copied at any time.
API Key Settings
When creating or editing an API key, configure these fields:
| Field | Description |
|---|---|
| Description | Required. Descriptive name for this key (e.g., "Zapier Integration", "CRM Sync") |
| Rate limit | Allowed number of requests per minute. Default is 60. Adjust based on integration needs. |
| API Roles | Required. Select the permission role this key uses. Determines what operations the key can perform. |
| Allowed IPs | Toggle to enable IP restrictions. When enabled, only requests from listed IPs are accepted. |
Rate Limit
The rate limit controls how many API requests this key can make per minute. The default is 60, but you can set this higher based on your server capacity and integration needs. High-volume integrations on powerful servers may use limits in the thousands.
Allowed IPs
When the Allowed IPs toggle is enabled:
- A text area appears to enter IP addresses
- Enter one IP address per line
- Only requests from listed IPs will be accepted
- Requests from other IPs receive an authentication error
For production integrations, always enable IP restrictions. This prevents unauthorized use even if the API key is compromised.
Managing API Keys
Edit a Key
- Click the Edit icon on the key row
- Modify settings in the modal
- Click Update
Toggle Status
Click the Status checkmark to enable or disable a key. Disabled keys reject all API requests.
Delete a Key
- Click the Delete icon (red trash)
- Confirm deletion
- The key is immediately revoked
Deleting or disabling an API key immediately stops all applications using that key. Ensure you update integrations before revoking access.
API Roles Tab
API Roles define what operations an API key can perform. Create roles with specific permissions, then assign those roles to API keys.
Viewing API Roles
| Column | Description |
|---|---|
| Role Name | Name of the permission role |
| Description | What this role is intended for |
| Actions | Edit, Delete |
Each role row has a Click to expand button to preview the assigned permissions.
Creating an API Role
- Click Add API Role
- Configure the role settings:
| Field | Description |
|---|---|
| Role Name | Required. Unique name for this role (e.g., "Contact Read Only", "Full Access") |
| Description | Optional. Describe what this role is for |
- Configure API Permissions (see below)
- Click Save
API Permissions
The permissions interface has two panels:
Left Panel - Modules: Scrollable list of API modules. Click a module to see its permissions.
Right Panel - Permissions: Checkboxes for individual operations within the selected module. Use Check All to grant all permissions for that module.
Available Modules
| Module | Controls |
|---|---|
| List Management | Create, view, edit, delete lists and list groups |
| Contact Management | Create, view, edit, delete contacts; import/export |
| Broadcast Management | Create, view, edit, delete broadcasts |
| Custom Fields | Manage custom field definitions |
| Suppression | Manage suppression lists |
| Actions | Manage triggers and automation actions |
| Bounce Addresses | Manage bounce mailbox configurations |
| FBL Addresses | Manage feedback loop addresses |
| Spintags | Manage content spinning tags |
| Bounce Rules | Configure bounce handling rules |
| Sending Domain | Manage sending domain settings |
| Broadcast Statistics | Access campaign statistics and reports |
| Logs | Access system and activity logs |
| User Management | Manage users (admin keys only) |
| Sending Nodes | Manage SMTP nodes |
| Web Forms | Manage subscription forms |
| Profile Fields | Manage contact profile fields |
| Groups | Manage list groups |
| V2 Sending Domains | The V2 sending domain endpoints — add a domain, verify ownership and DNS records, switch features on or off, manage DKIM keys |
| V2 User Management | The V2 user endpoints — create, suspend, unsuspend, change package or password (admin keys only) |
V2 Sending Domains appears on installations updated to 7.1, and V2 User Management on installations updated to 7.0. Roles that already existed when the update ran were granted the new permissions automatically, so integrations that worked before the update keep working.
Roles you create afterwards start without them. If a new role's key is refused with a permission error on a V2 endpoint, open the role and tick the permissions in the matching V2 module.
Example: List Management Permissions
| Permission | Description |
|---|---|
| Add New List | Create new contact lists |
| View List | View individual list details |
| Views Lists | List all lists |
| Edit | Modify list settings |
| Delete | Remove lists |
| Delete List Group | Remove list groups |
| Get List Groups | Retrieve list group data |
Example: V2 Sending Domains Permissions
| Permission | Description |
|---|---|
| Sending domain policy | Read what the account is allowed to do — domains left on the package, features the package forces, tracking methods on offer, verification settings |
| List sending domains | List the account's sending domains |
| View sending domain | Read a single sending domain |
| Add sending domain | Add a sending domain |
| Update sending domain | Change prefixes, redirection type, and feature switches |
| Delete sending domain | Remove a sending domain, optionally reassigning what still uses it |
| View DNS records | Read the records the domain still needs, optionally with the values published today |
| Verify domain ownership | Run the ownership check |
| Verify DNS records | Run the DKIM, tracking, bounce, and DMARC checks |
| Enable / disable features | Switch DKIM, tracking, bounce handling, DMARC, secure links, and the domain's active state on or off |
| Regenerate DKIM keys | Generate a fresh DKIM key pair for the domain |
| View DKIM keys | Read the domain's public DKIM key material — the private key is never returned by the API |
Granting a permission does not override Application Settings or the account's package. A key with Enable / disable features still cannot switch off a feature the package forces, and Regenerate DKIM keys has no effect where the administrator has disabled key regeneration.
Role Examples
Read-Only Role:
- Views Lists, View List (List Management)
- View contacts (Contact Management)
- View statistics (Broadcast Statistics)
Contact Sync Role:
- All List Management permissions
- All Contact Management permissions
- Views Broadcasts (Broadcast Management)
Full Integration Role:
- All permissions across all modules
Managing API Roles
Edit a Role
- Click the Edit icon on the role row
- Modify name, description, or permissions
- Click Save
Changes affect all API keys using this role immediately.
Delete a Role
- Click the Delete icon (red trash)
- Confirm deletion
You cannot delete a role that is assigned to active API keys. First reassign or delete those keys.
Using the API
Authentication
V2 API (Recommended)
V2 API endpoints require a Bearer token in the Authorization header. Query parameter authentication is not supported for V2.
Authorization: Bearer YOUR_API_KEY
V1 API (Legacy)
V1 API endpoints accept authentication via either the Authorization header or a query parameter:
Authorization: Bearer YOUR_API_KEY
?api_token=YOUR_API_KEY
The V2 API enforces Bearer-only authentication to prevent token leakage through URLs, server access logs, and HTTP referrer headers. Migrate to V2 endpoints where available.
Base URLs
# V2 API
https://your-mumara-domain.com/api/v2/
# V1 API (legacy)
https://your-mumara-domain.com/api/
Example Requests
V2 API
curl -X GET "https://your-domain.com/api/v2/lists" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Accept: application/json"
{
"success": true,
"data": [ ... ],
"meta": {
"current_page": 1,
"per_page": 25,
"total": 10,
"last_page": 1,
"from": 1,
"to": 10
}
}
V1 API
curl -X POST "https://your-domain.com/api/addList" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Accept: application/json" \
-d "name=My List&group_id=1"
{
"success": true,
"data": { ... },
"message": "Operation completed successfully"
}
Rate Limiting
When a key exceeds its rate limit:
- HTTP 429 (Too Many Requests) is returned
- Response headers indicate when to retry:
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1706745600
Implement exponential backoff in your integration to handle rate limits gracefully.
Best Practices
Security
- Use IP restrictions for production keys
- Create separate keys for each integration (don't share keys between applications)
- Minimum permissions - Only grant permissions the integration actually needs
- Regular audits - Review keys and remove unused ones
- Never expose keys - Don't commit to version control or expose in client-side code
Organization
- Descriptive names - Use descriptions like "Zapier - Contact Sync" not "API Key 1"
- Role per purpose - Create specific roles rather than using one "full access" role
- Document integrations - Track which systems use which keys
Monitoring
- Check Last Accessed - Keys that haven't been used recently may be candidates for deletion
- Review logs - Monitor API activity for unusual patterns
- Test after changes - Verify integrations work after modifying roles
Troubleshooting
Authentication Failed (401)
Possible causes:
- Invalid API key
- Key disabled or deleted
- Incorrect Authorization header format
- Using query parameter
?api_token=with V2 API (not supported)
Solutions:
- Verify the key exists and is active
- Check header format:
Authorization: Bearer KEY - V2 API requires Bearer token in the header — query parameters are not accepted
- Create a new key if needed
Permission Denied (403)
Possible causes:
- API role doesn't include the requested operation
- Trying to access another user's resources
Solutions:
- Check the role's permissions for the module
- Add missing permissions to the role
- Verify you're accessing resources owned by the key's owner
IP Blocked (403)
Possible causes:
- Request from IP not in Allowed IPs list
- IP changed (VPN, proxy, cloud infrastructure)
Solutions:
- Add the requesting IP to Allowed IPs
- Disable IP restrictions for development/testing
- Use a static IP for production integrations
Rate Limited (429)
Possible causes:
- Too many requests within the minute window
Solutions:
- Implement request throttling
- Increase the key's rate limit
- Batch operations where possible
- Wait for the rate limit window to reset
Next Steps
- Application Settings - Configure application options
- Licensing - Manage licensing
- Webhooks - Configure event notifications