API Overview

The Mumara ONE REST API lets your own applications, such as your CRM, website backend, data pipeline or automation tool, work with your account without using the app: add contacts, manage lists, create broadcasts, read statistics, set up sending domains and more.

Mumara ONE runs on Mumara Campaigns, and the REST API is the Mumara Campaigns API. The API reference documents every endpoint, parameter and response, and applies to Mumara ONE as written; only the base URL is different. This page covers what you need to know before you start, and what's different in Mumara ONE.

Base URLs

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

Always use https://.

Authentication

Every request needs an API key. Create one under Setup → API Keys, where you also choose what the key may do, which IP addresses may use it and its rate limit. See API Keys.

Send the key as a Bearer token:

Authorization: Bearer YOUR_API_KEY

V2 accepts the key only in this header. V1 also accepts it as an api_token parameter, but the header is safer: keys in URLs end up in logs and browser history.

To check that a key works, ask for your own profile:

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

A working key returns "success": true and your account details in data. A 401 means the key is missing, wrong or switched off, or your IP address isn't in the key's Allowed IPs.

V1 and V2

	V2	V1
Base URL	https://one.mumara.com/api/v2/	https://one.mumara.com/api/
Style	Resources and HTTP methods, such as GET /lists and POST /contacts	Named actions, such as GET /getLists and POST /addContact
Authentication	Authorization: Bearer header only	Bearer header or api_token parameter
Request bodies	JSON	JSON or form fields
Responses	success, data, meta and message	status and result
Errors	An HTTP status plus an error object with a code	"status": "error", sometimes with HTTP 200
Paging	page and per_page	limit_start and limit_count on list endpoints that support them

Use V2 for new integrations. Use V1 only for what V2 doesn't cover yet, listed under What the API covers.

Requests

• Send request bodies as JSON, with Content-Type: application/json.
• Send Accept: application/json, so errors come back as JSON too.
• Resource IDs go in the path, for example GET /api/v2/lists/12.
• Dates in V2 responses use ISO 8601 with a time zone offset, for example 2026-08-01T09:30:00+00:00.
• Some V2 resources have batch endpoints, such as POST /contacts/batch for up to 1,000 contacts in one request, and DELETE /suppressions/batch. Prefer them to many single requests.

Responses

A V2 request for a single item returns it in data:

{
  "success": true,
  "data": {
    "id": 12,
    "name": "Newsletter",
    "owner_name": "Example Store",
    "owner_email": "news@example.com",
    "reply_email": "support@example.com",
    "subscribers_count": 1520,
    "created_at": "2026-08-01T09:30:00+00:00",
    "updated_at": "2026-09-20T14:02:11+00:00"
  }
}

Creating something returns HTTP 201 with the new item in data and a message, such as "List created successfully". Updating and deleting return 200 with a message.

V1 responses look like this:

{
  "status": "success",
  "result": []
}

Pagination

V2 list endpoints are paged. Pass page (from 1) and per_page (1 to 100, default 25):

curl "https://one.mumara.com/api/v2/contacts?page=2&per_page=100" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

The response has the items in data and the paging details in meta:

{
  "success": true,
  "data": [],
  "meta": {
    "current_page": 2,
    "per_page": 100,
    "total": 1520,
    "last_page": 16,
    "from": 101,
    "to": 200
  }
}

Field	Meaning
current_page	The page you asked for.
per_page	Items per page.
total	Items across all pages.
last_page	The number of the last page. Stop when current_page reaches it.
from, to	The positions of the first and last items on this page, or null for an empty page.

V1 list endpoints that support paging take limit_start (how many items to skip, default 0) and limit_count (how many to return, default 25). The API reference says which endpoints support them.

Errors

V2 errors have "success": false and an error object:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The given data was invalid.",
    "details": {
      "email": ["The email field is required."]
    }
  }
}

HTTP status	code	What it means
401	UNAUTHORIZED	The key is missing, wrong or switched off, or the request came from an IP address the key doesn't allow.
403	FORBIDDEN	The key isn't allowed to do this. Check its permissions under Setup → API Keys.
404	NOT_FOUND	The item doesn't exist, or doesn't belong to your account.
409	CONFLICT	The request clashes with something that exists, such as a duplicate.
422	VALIDATION_ERROR	A field is missing or invalid. details lists the problems by field.
429		Too many requests. See Rate limits.
5xx		Something went wrong on our side. Retry later, with a growing delay.

A few responses don't follow the V2 format, so check the HTTP status first:

• A path that doesn't exist returns 404 with "status": "error" and a list of suggested_uris.
• A 429 has a short JSON body without success or error.

V1 errors return "status": "error" and the reason in result. Some return HTTP 200, so always check status in V1 responses.

Rate limits

Each API key may make as many requests per minute as its Rate limit, which you set on the key under Setup → API Keys. Every response tells you where you stand:

Header	Meaning
X-RateLimit-Limit	Requests this key may make per minute.
X-RateLimit-Remaining	Requests left in the current minute.
Retry-After	On a 429 only: seconds to wait before trying again.
X-RateLimit-Reset	On a 429 only: when you can try again, as a Unix timestamp.

When X-RateLimit-Remaining gets low, slow down. After a 429, wait for Retry-After before sending the next request, rather than retrying straight away. The limit counts per key, so give each integration its own key.

What the API covers

In V2:

Area	Endpoints	Notes
Lists	/lists
Contacts	/contacts, /contacts/batch
Custom fields	/custom-fields, /lists/{listId}/custom-fields
Segments	/segments	Also counts the contacts in a segment.
Suppressions	/suppressions, /suppressions/batch
Broadcasts	/broadcasts	Create and manage the emails themselves.
Drip campaigns	/drips	List, view and delete.
Triggers	/triggers	List, view, update and delete. See Triggers.
Web forms	/web-forms	Includes the embed code for a form.
Groups	/groups/{module}	The groups that organise lists, broadcasts and so on.
Spin tags	/spin-tags
Broadcast statistics	/stats/broadcasts/{id}/...	Summary, opens, clicks, bounces, unsubscribes, complaints and logs.
Sending domains	/sending-domains	Add and verify domains, read DNS records, switch features, rotate DKIM keys. See Sending Domains.
Your profile	/me	Read and update your own account details.

Only in V1, for now:

To	Use
Schedule a broadcast to send	POST /api/broadcastSchedule
Import contacts from a file	POST /api/importContacts
Create a trigger	POST /api/addTrigger
Create a drip campaign	POST /api/addDrip
Read your activity logs	GET /api/getActivityLogs

Parts of the reference you don't need

The reference also documents endpoints for self-hosted Mumara Campaigns that don't apply to Mumara ONE:

• Sending nodes, bounce mailboxes, bounce rules and FBL accounts. Mumara ONE runs your sending servers, bounce handling and feedback loops for you.
• Users. These are for administrators of a Mumara Campaigns installation.
• Webhooks (/v2/webhooks). This is a separate feature: webhooks created there don't appear under Actions → Webhooks and don't send the email events described in Webhooks. Create your webhooks in the app.
• Sending single emails (/sendEmail, /v2/email/send). In Mumara ONE, send transactional email through a Bridge with the Sending API.

The REST API and the Sending API

Mumara ONE has two APIs. They do different jobs and use different credentials:

	REST API (this page)	Sending API
What it's for	Managing your account: contacts, lists, campaigns, statistics, domains	Sending one transactional email
Address	https://one.mumara.com/api/v2/ and /api/	POST https://api.mumara.com/sendEmail
Credential	An API key from Setup → API Keys	A Bridge's One Connect Key from Transactional → Bridges
Permissions	Chosen per key	The key can only send through its Bridge
Rate-limit headers	Yes	No; sending counts against your plan's transactional allowance

An API key doesn't work on the Sending API, and a One Connect Key doesn't work on the REST API.

Events: use webhooks, not polling

To learn about deliveries, bounces, opens, clicks and complaints as they happen, set up webhooks under Actions → Webhooks instead of polling the statistics endpoints. Mumara ONE then sends each event to your URL, signed so you can verify it.

Good practice

• Call the API from your server, never from a browser or a mobile app. Anyone who has the key can act on your account.
• One key per integration, with only the permissions it needs. See API Keys.
• Handle errors by HTTP status, and retry 429 and 5xx responses with a growing delay.
• Page through large lists with per_page=100 rather than many small pages.
• Use batch endpoints when you add or remove many contacts or suppressions.

Next steps

• API Keys: create a key and choose its permissions
• API reference: every endpoint, parameter and response
• Webhook signatures: verify the events Mumara ONE sends you
• Sending API: send transactional email through a Bridge