Developer · REST · ACL-driven
A comprehensive REST API across contacts, broadcasts, drips, triggers, segments, sending infrastructure, suppression, statistics. Super-detailed ACL, reusable roles that generate any number of API keys, per-key rate limits configurable up to unlimited, per-key IP restrictions, JSON-only responses.
$ curl -X POST https://app.mumara.com/api/v2/contacts \
-H "Authorization: Bearer mc_live_..." \
-H "Content-Type: application/json" \
-d '{
"email": "[email protected]",
"first_name": "Alex",
"list_id": 42,
"status": "active"
}'
# Response (201 Created)
{
"success": true,
"data": {
"id": 18293,
"email": "[email protected]",
"list_id": 42,
"created_at": "2026-05-22T14:08:22Z"
}
}Built for production
The API reaches every primitive the UI does — and a few it doesn't. Every endpoint follows the same auth, pagination, error, and rate-limit conventions, so the second integration is faster than the first.
The security primitives
Where most APIs ship a thin auth layer and ask you to build everything else, Mumara's API treats roles, limits, and network restriction as first-class primitives. Compose them per integration.
API roles are built from a super-detailed permission tree — any platform action can be granted or denied individually. Build a role once; generate any number of API keys from it. Update the role and every key inherits the change instantly. One role → many keys, by design.
Set the per-minute throttle per API key. Configure it to whatever your integration needs — modest caps for partner / experimental keys, unlimited for trusted internal services. Standard X-RateLimit-* headers on every response so your client can pace itself.
Each API key has an optional IP allowlist — specific addresses, ranges, or CIDR. Calls from outside the allowlist are rejected at the auth layer, before they touch the endpoint. Critical for production keys living in known environments and for hardening reseller / agency integrations.
Four endpoints, four anatomies
The same conventions across every resource. Once you've written the first call, the others write themselves.
GET /api/v2/contacts?list_id=42&page=2&per_page=50
# Response 200
{
"data": [
{ "id": 18244, "email": ... },
...
],
"meta": {
"current_page": 2,
"per_page": 50,
"total": 12048,
"last_page": 241
}
}POST /api/v2/suppressions/batch
{
"type": "email",
"reason": "manual",
"entries": [
"[email protected]",
"[email protected]",
"[email protected]"
]
}
# Response 200 — added 3, skipped 0POST /api/v2/dynamicTemplate/17
{
"to": "[email protected]",
"variables": {
"first_name": "Alex",
"order_id": "ORD-9281",
"total": "$148.20"
}
}
# Response 202 — queued for send# Response 422
{
"success": false,
"error": {
"code": "validation_failed",
"message": "The given data was invalid.",
"details": {
"email": ["must be a valid email"],
"list_id": ["does not exist"]
}
}
}From signup to first call
The path every new integration follows. Everything happens inside the platform — no engineering tickets, no SDK install, no waiting on a third-party vendor.
Step 1
Tools → API Management → Roles. Tick the actions this integration class needs (e.g. read+create contacts, send broadcasts) — any permission can be granted, any can be denied. Save the role; you'll generate any number of keys from it.
Step 2
Click + Add Key. Bind it to the role. Set the per-minute rate limit (configure up to unlimited) and the IP allowlist (specific IPs, ranges, CIDR). Copy the key once — it never appears again.
Step 3
curl, Postman, or your language of choice. Authorization: Bearer <token>; Content-Type: application/json. 201 Created on success.
Step 4
Lists return data + meta. Use meta.last_page + meta.current_page to walk through. per_page defaults to 25, caps at 100.
Step 5
Add a webhook endpoint for contact / broadcast events. HMAC signature on every payload. Auto-disables after 10 consecutive failures so a broken endpoint never silently drops events forever.
What teams build on it
Common questions
Pass `Authorization: Bearer <key>` on every request. The key never travels in the URL, so it doesn't end up in webserver access logs, browser history, or referer headers. Keys are generated in Tools → API Management, are bound to an API role, are configurable per-key for rate limit and IP allowlist, and update a last-access timestamp on every call.
An API role is a set of permissions a key is allowed to use — built from a super-detailed ACL. Any platform action can be granted or denied individually: Contacts, Lists, Broadcasts, Segments, Custom Fields, Sending Nodes, Sending Domains, Drips, Triggers, Suppression, Statistics, Webhooks, and so on. Tick the actions this integration class needs, untick the rest. Roles are **reusable** — build a role once, generate any number of API keys from it. When the role definition changes, every key using it inherits the change immediately.
Per-key, fully configurable. Set the per-minute throttle to whatever the integration needs — modest caps for partner / experimental keys, configure up to unlimited for trusted internal services. Every response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` headers so your client can pace itself; exceeding returns HTTP 429 with `Retry-After`. Set the limit once per key; change it any time without rotating the key.
Yes — every API key has an optional IP allowlist. Specify individual IPs, ranges, or CIDR notation; calls from outside the allowlist are rejected at the auth layer before they touch the endpoint. Critical for keys that live in known production environments (your servers' static IPs) and for hardening keys you give to resellers, partners, or agency integrations.
Yes — anywhere the workflow benefits. Contacts have batch add and batch delete. Suppression has batch suppress and batch unsuppress. Web forms, FBL accounts, spin tags, profile fields, triggers, drips, segments — all have bulk-delete endpoints. Use these in preference to looped single-item calls when moving large volumes; you'll save API calls, ratelimit budget, and roundtrip latency.
First-class feature, not an addon. Configure a webhook endpoint with the events you want — `contact.subscribed`, `contact.unsubscribed`, `contact.bounced`, `contact.complained`, `broadcast.sent`, `broadcast.opened`, `broadcast.clicked`. Each payload is JSON and includes an HMAC-SHA256 signature when you set a secret. Failed deliveries auto-retry; consecutive failures auto-disable the webhook so a broken endpoint never silently drops events forever. A test endpoint lets you trigger sample deliveries from the UI.
Consistent across endpoints. Successful responses return `{ "success": true, "data": { … } }` (plus `meta` on paginated lists). Failed responses return `{ "success": false, "error": { "code": "…", "message": "…", "details": { … } } }`. Validation errors (HTTP 422) populate `details` with per-field arrays of human-readable messages — useful for surfacing form errors to your end users without a second roundtrip.
The complete reference lives in the [Mumara Campaigns API documentation](https://docs.mumara.com/campaigns/api/) — every endpoint, every parameter, every response shape with example payloads. The in-app API Management page also lists the routes available on your installation. For self-hosted, the platform admin can point you at the route file directly.
Generate the replacement key first (same or different role), deploy your application with the new key, then delete the old key. Keys are soft-deleted, so an accidental revoke is recoverable by the platform admin. The per-key IP allowlist and status flags also let you 'soft-revoke' a key instantly (toggle status to inactive) without removing it.
Yes — via Dynamic Templates. Create a Broadcast template in the UI, then POST to the dynamic-template endpoint with per-recipient variables. Mumara handles the merge, the send, the deliverability, and the reporting. Same suppression, same reputation, same sending nodes — your transactional traffic doesn't need a separate ESP.
Related
API events pushed to your endpoints — HMAC-signed, retry-resilient, auto-disable on persistent failure.
Read moreThe most-used API surface. Single-contact and batch endpoints, list management, custom fields.
Read moreList, get, schedule broadcasts via API. Dynamic Templates make transactional sends straightforward.
Read moreTrigger configuration is API-accessible. Build, edit, and inspect triggers programmatically.
Read moreAPI roles share the same super-detailed permission tree as admin roles — same granularity, same reusability pattern.
Read moreStatistics endpoints return the same data the in-app reports show — feed your own dashboards.
Read moreMumara Campaigns · REST API
The REST API ships with every Mumara Campaigns plan — Self-Hosted and Mumara Machine. No tier-gating on endpoints. Reusable ACL roles, per-key rate limits configurable up to unlimited, per-key IP restrictions — all under your control. Full reference at docs.mumara.com/campaigns/api.