Skip to content
Start freeGet started
Get started

Authentication & API keys

Every request carries an API key in the Authorization header. Keys belong to a workspace, carry a set of permissions, and can be limited to specific audiences.

Send the key as a Bearer token#

curl https://www.mailmanny.com/api/v1/audiences \  -H "Authorization: Bearer $MAILMANNY_API_KEY"

Keys look like mm_live_ followed by 32 letters and digits. Mailmanny stores only a hash of each key, so it can show you the full key once, when you create it. After that the list shows its first characters (mm_live_8fK2mQ9x…) and when it was last used.

Permissions#

Pick only what the key needs. A request the key isn't allowed to make fails with 403 restricted_api_key.

fullFull access
Everything below, plus reading any email, skipping double opt-in with a consent record and erasing contacts.
contacts:readRead contacts
List and look up contacts in your audiences.
contacts:writeAdd & update contacts
Add, update, tag, unsubscribe and archive contacts.
emails:sendSend emails
Send transactional email and check the status of emails sent with this key.
templates:readRead templates
List and fetch your saved templates.
templates:writePush templates
Create, update and delete templates (used by mailmanny templates push).
events:writeTrack events
Send custom events that start API-event automations.

templates:write includes templates:read. Listing audiences (GET /audiences) works with any of contacts:read, contacts:write or events:write, so integrations can look up the audience they write to.

Response403 ForbiddenJSON
{  "statusCode": 403,  "name": "restricted_api_key",  "message": "This API key can't do that. It needs the \"contacts:read\" (read contacts) permission. Create a key with it in Settings → API keys."}

Presets#

The create dialog offers three starting points:

  • Full access (full): For your own backend. Can do everything.
  • Audience key (contacts:write): Adds and updates people in the audiences you pick. Can't read your list, send email or erase anyone.
  • Sending only (emails:send): Sends transactional email. Can't read or change contacts.

Audience keys#

Like Mailchimp's audience-level keys, a key can be limited to one or more audiences. It then only sees those audiences: listing returns just them, and any other audience id answers 404 not_found, exactly as if it didn't exist. Combined with the contacts:write permission alone, that gives you a key that can add and update people in your newsletter but can't read the list, send email or erase anyone, which is the right key for signup plugins, Zapier-style tools and contractors.

Audience restrictions apply to contacts, tags and events. Sending email isn't tied to an audience, so a sending key works across the workspace.

Rotate and revoke keys#

  1. Create a new key with the same permissions.
  2. Deploy it to your servers.
  3. Watch the old key's Last used time in Settings → API keys stop moving, then revoke it.

Revoking is immediate and permanent: the next request with that key fails with 401 invalid_api_key. If a key leaks, revoke it first and rotate second. Only workspace owners and admins can create or revoke keys; a workspace can have up to 50 active keys.

Authentication errors#

missing_api_key401
No Authorization header.
invalid_api_key401
The key is malformed, unknown or revoked.
restricted_api_key403
The key lacks the permission this endpoint needs.
browser_request_blocked403
The request came from a web page. Call the API from your server.