API Keys

API keys let your own applications, such as a CRM, your website's backend, an automation tool or a script, work with your Mumara ONE account through the REST API: add contacts, manage lists, create broadcasts, read statistics, set up sending domains and more. Each key has its own permissions, so an integration can only do what you allow.

Go to Setup → API Keys to manage them.

The API Keys page

The page lists every key in your account:

Column	What it shows
API Key	The key itself, which your application sends with each request.
Description	What the key is for.
API Name	The name you gave the key.
Owner	Your account name and email address.
Allowed IPs	The IP addresses allowed to use the key, if you restricted it.
Last Accessed	When the key was last used, or Never.
Status	A switch: on means the key works, off means every request with it is refused.
Actions	A pencil icon to edit the key, a trash icon to delete it.

Create an API key

1. Go to Setup → API Keys and click Create an API Key.

2. Fill in the key's settings:

   Field	What to enter
   API Name	Required. A name that says what the key is for, for example CRM contact sync.
   Description	Optional notes about the integration.
   Rate limit	How many requests per minute the key may make. The field starts at 60. Set it to what your integration really needs.
   Allowed IPs	Optional. Switch it on and enter the IP addresses allowed to use the key, one per line. The dialog shows your Current IP Address for reference. Leave it off to allow requests from anywhere.

3. Under API Permissions, click a module in the Modules list, then tick the operations the key may perform in that module. Check All ticks every operation in the selected module. Repeat for each module the integration needs.

4. Click Create Key.

The new key appears in the list. Copy it from the API Key column into your application's settings.

Why the dialog says "Add API Role"

The dialog is titled Add API Role, and API Role Settings when you edit a key, because each key carries its own set of permissions, called a role. You don't manage roles separately: they're created, changed and deleted along with their key.

Permissions

Permissions are grouped into modules. In each one you choose the individual operations a key may perform, for example viewing lists without being able to delete them.

Module	What it covers
List Management	Contact lists and list groups: add, view, edit and delete
Contact Management	Contacts: add, view, edit and delete them, mark them as unsubscribed, bounced or complained, and import contacts
Broadcast Management	Broadcasts, broadcast groups, scheduled broadcasts and drips
Custom Fields	Custom fields and their use on lists
Suppression	Suppression entries: add, view and delete
Actions	Scheduling broadcasts, and adding, listing and deleting triggers
Spintags	Spintax tags
Sending Domain	Sending domains through the V1 API: add, list, update and delete
Broadcast Statistics	Broadcast results: summary, opens, clicks, bounces, unsubscribes, complaints and logs
Logs	Activity logs
Web Forms	Listing and deleting web forms
Groups	Listing groups
V2 Sending Domains	Everything on Sending Domains through the V2 API: add a domain, verify ownership and DNS records, switch features on or off, regenerate DKIM keys
Bounce Addresses, Sending Nodes	Kept for compatibility with Mumara Campaigns. Mumara ONE manages bounce handling and sending servers for you, so most integrations don't need these.

The V2 Sending Domains module has these permissions:

Permission	Allows the key to
Sending domain policy	Read what your account may do: domains left on your plan, required features, verification settings
List sending domains	List your sending domains
View sending domain	Read one sending domain
Add sending domain	Add a sending domain
Update sending domain	Change a domain's settings
Delete sending domain	Delete a domain, optionally moving what uses it to another domain
View DNS records	Read the records the domain needs, optionally with the values DNS returns today
Verify domain ownership	Run the ownership check
Verify DNS records	Run the DKIM, tracking, bounce and DMARC checks
Enable / disable features	Switch features such as DMARC, secure links and the domain itself on or off
Regenerate DKIM keys	Create a new DKIM key pair
View DKIM keys	Read the domain's public DKIM key. The private key is never returned.

Permissions never go beyond your plan. For example, a key with Enable / disable features still can't switch off DKIM signing where your plan requires it.

Manage your keys

• Edit a key. Click the pencil icon, change its settings or permissions, and click Update. Changes apply to the key straight away.
• Disable a key. Switch off its Status. Every request with it is refused until you switch it back on. This is a quick way to cut off an integration without losing its settings.
• Delete a key. Click the trash icon and confirm. The key and its permissions are removed for good.

Disabling or deleting a key is immediate

Every application using the key stops working at once. Update your integrations with a new key before you revoke the old one.

Use your key

Base URLs

https://one.mumara.com/api/v2/    V2 API (recommended)
https://one.mumara.com/api/       V1 API (legacy)

Authentication

The V2 API only accepts the key as a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_KEY

The V1 API accepts the same header, or the key as an api_token parameter. Prefer the header: keys in URLs end up in server logs, browser history and referrer headers.

Example request

curl "https://one.mumara.com/api/v2/lists" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

A successful V2 response has "success": true, the results in data, and paging details in meta. The API reference documents every endpoint, its parameters and its responses. Mumara ONE uses the same API as Mumara Campaigns, so the reference applies as written; only the base URL is different.

Errors and rate limits

Status	What it means	What to check
401	The key is missing, wrong or disabled, or the request came from an IP address that isn't in the key's Allowed IPs.	The Authorization: Bearer header, the key's Status switch, and the IP address your server sends from.
403	The key doesn't have permission for this operation.	Edit the key and tick the missing permission in the right module.
429	The key made more requests in a minute than its Rate limit allows.	Wait until the time given in Retry-After, then slow down or raise the key's rate limit.

V2 errors come back as JSON with a code and a message, for example:

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required. Provide a Bearer token in the Authorization header."
  }
}

Every response carries X-RateLimit-Limit and X-RateLimit-Remaining headers, so your integration can pace itself. When a key goes over its limit, the response also includes Retry-After (seconds to wait) and X-RateLimit-Reset. Build in a retry with a growing delay rather than retrying straight away.

Requests from cloud servers

If your application runs on a platform whose outgoing IP address changes, such as serverless functions or autoscaling servers, a key with Allowed IPs will start failing with 401 whenever the address changes. Use a static outgoing IP, or leave Allowed IPs off for that key.

Good practice

• One key per integration. You can then see each one's Last Accessed, and revoke one without breaking the others.
• Grant only what's needed. A contact sync doesn't need to delete broadcasts.
• Restrict by IP for server-to-server integrations with a fixed address.
• Keep keys secret. Never put a key in browser or mobile app code, or commit it to version control. Anyone with the key can act on your account within its permissions.
• Clean up. Delete keys whose Last Accessed shows they're no longer used.

Next steps

• API reference: every endpoint, parameter and response
• Sending Domains: what the V2 Sending Domains endpoints manage
• Bridges: transactional email from your application uses a Bridge, with its own SMTP or HTTP API credentials