API

The API lets your website, shop or other tools talk to SendKettle. You can add and update contacts, change their tags, read campaigns and reports, and send one-off emails such as receipts.

All requests and responses use JSON. The examples use https://mail.example.com as the address of your SendKettle. Replace it with yours.

This guide covers keys, contacts, tags, events, journeys, reports and webhook subscriptions. Creating and sending campaigns, report details, audience fields and segments, batches, templates, files, landing pages, text messages, search, forgetting contacts, exports, apps that connect with OAuth and the OpenAPI description are in API: campaigns, reports, batches and apps.

Create an API key

  1. Click your name at the bottom of the menu and then Profile to open Your profile.
  2. Under API keys, type a name for the key, for example "Website".
  3. Choose when it expires: in 30, 90 or 365 days, or No expiry date.
  4. Type your current password. If you logged in with single sign-on in the last 15 minutes, there is no password box.
  5. Click Create key.
  6. Copy the key from Your new key right away. It starts with mr_ and is shown only once.

The list shows each key's name, its first characters, when it was last used and when it expires. Click Revoke to delete a key. Requests with it stop working at once.

Every time a key is created on your account, you get an email with its name, its first characters and when it expires (never the key itself). If you did not create it, revoke it, change your password and tell an admin. Admins and Owners see the keys of the whole team under Settings, Team, API keys and can revoke them there; you get an email when they revoke one of yours (see Team and roles).

Your keys are revoked by themselves when you change or reset your password, or turn two-factor authentication on or off, so a key someone made with a stolen password or session stops working once you fix it. Create new keys afterwards. While your team requires two-factor authentication, keys of people who haven't set it up get 403 (single sign-on accounts excepted).

A key acts as you, with your role. It belongs to the workspace you were in when you created it and only sees that workspace's lists, contacts and campaigns, so create a key in each workspace you want to reach (see Workspaces). A Viewer's key can only read. Most write actions need a Manager key or higher (see permissions). Keep keys secret: anyone with a key can do what you can do.

Authentication

Send the key in the Authorization header of every request:

curl https://mail.example.com/api/v1/ping \
  -H "Authorization: Bearer mr_your_key_here" \
  -H "Accept: application/json"

Add Content-Type: application/json to requests with a body.

Limits

You can make 120 requests per minute. Each response has an X-RateLimit-Remaining header with the number you have left.

Endpoints

Method Path What it does
GET /api/v1/ping Check your key.
GET /api/v1/audiences List audiences with their custom fields and interests.
GET /api/v1/audiences/{id}/interests List the interest groups of an audience.
POST /api/v1/audiences/{id}/interests Add an interest group.
GET /api/v1/audiences/{id}/contacts List contacts of an audience.
PUT /api/v1/audiences/{id}/contacts Create or update a contact by email.
GET /api/v1/audiences/{id}/contacts/{email} Get one contact.
DELETE /api/v1/audiences/{id}/contacts/{email} Delete one contact.
POST /api/v1/audiences/{id}/contacts/{email}/tags Add or remove tags.
GET /api/v1/audiences/{id}/contacts/{email}/notes List a contact's notes.
POST /api/v1/audiences/{id}/contacts/{email}/notes Add a note.
GET /api/v1/audiences/{id}/contacts/{email}/activity A contact's activity, newest first.
POST /api/v1/events Record a custom event for a contact.
GET /api/v1/journeys List journeys and their steps.
GET /api/v1/journeys/{id}/contacts List who is in a journey now.
POST /api/v1/journeys/{id}/contacts Put a contact in a journey.
DELETE /api/v1/journeys/{id}/contacts/{email} Take a contact out of a journey.
POST /api/v1/journeys/{id}/contacts/{email}/skip Move a contact past the step they wait at.
POST /api/v1/stock-alerts Ask to hear when a product is back in stock.
GET /api/v1/campaigns List campaigns. More campaign endpoints are in the second API guide.
GET /api/v1/campaigns/{id}/report Get a campaign's numbers.
GET /api/v1/reports/channels Numbers per campaign, journey or text message over a period.
POST /api/v1/messages/send Send a transactional email (one or more recipients, or a template).
POST /api/v1/messages/send-raw Send a complete MIME message.
GET /api/v1/messages Search the transactional message log.
GET /api/v1/messages/{id} One message with its history and content.
GET /api/v1/messages/scheduled Scheduled and queued messages.
POST /api/v1/messages/{id}/cancel Cancel a scheduled or queued message.
POST /api/v1/messages/{id}/reschedule Move a scheduled message to another time.
GET /api/v1/messages/stats Transactional numbers per day.
GET /api/v1/transactional/templates List transactional templates.
GET, PUT, DELETE /api/v1/transactional/templates/{name} Get, create or update, or delete a template.
POST /api/v1/transactional/templates/{name}/publish Publish a template's draft.
POST /api/v1/transactional/templates/{name}/render Render a template with variables without sending.
GET, POST /api/v1/lists/{deny or allow} List or add transactional deny or allow list entries.
DELETE /api/v1/lists/{deny or allow}/{entry} Remove an entry.
POST /api/v1/sms/send Send a one-off text message.
GET /api/v1/sms/{id} Get the status of a one-off text message.
GET /api/v1/hooks List your webhook subscriptions.
POST /api/v1/hooks Subscribe an address to an event (used by Zapier).
DELETE /api/v1/hooks/{id} Remove a subscription.
GET /api/v1/hooks/events List the events you can subscribe to.
GET /api/v1/hooks/samples/{event} Sample data for an event.

{id} is the number of the audience or campaign. Get audience numbers from GET /api/v1/audiences. {email} is the contact's email address. Encode it for a URL if it contains special characters, for example + becomes %2B.

Shops send customers, products, orders, carts, promo codes and browsing through the store endpoints under /api/v1/store. They have their own guide: Store API.

Check your key

curl https://mail.example.com/api/v1/ping \
  -H "Authorization: Bearer mr_your_key_here"
{"ok": true, "user": "admin@example.com", "role": "owner"}

List audiences

curl https://mail.example.com/api/v1/audiences \
  -H "Authorization: Bearer mr_your_key_here"
{
  "data": [
    {
      "id": 1,
      "name": "Newsletter",
      "contacts": 5,
      "double_opt_in": true,
      "fields": [
        {"key": "birthday", "label": "Birthday", "type": "birthday"}
      ],
      "interests": [
        {"id": 1, "name": "News", "show_on_form": true}
      ]
    }
  ]
}

contacts counts contacts of every status.

List contacts

Needs the Manager role or higher, because it works like an export.

curl "https://mail.example.com/api/v1/audiences/1/contacts?status=subscribed&per_page=100&page=1" \
  -H "Authorization: Bearer mr_your_key_here"
Query parameter Meaning
status Optional. Only contacts with this status: subscribed, pending, unsubscribed or cleaned.
per_page Optional. 1 to 1000, default 100.
page Optional. Page number, default 1.
{
  "data": [
    {
      "id": 1,
      "email": "jane@example.com",
      "first_name": "Jane",
      "last_name": "Doe",
      "status": "subscribed",
      "fields": {"birthday": "03-14"},
      "tags": ["vip"],
      "interests": ["News"],
      "email_frequency": "all",
      "paused_until": null,
      "unsubscribe_reason": null,
      "source": "manual",
      "subscribed_at": "2026-09-19T17:21:35+00:00",
      "created_at": "2026-11-18T17:21:35+00:00",
      "phone": "+31612345678",
      "sms_consent": "subscribed",
      "sms_consent_at": "2026-10-01T12:00:00+00:00",
      "sms_consent_source": "checkout",
      "sms_unsubscribed_at": null,
      "postal_address": {"line1": "185 Berry St", "line2": "", "city": "San Francisco", "state": "CA", "postal_code": "94107", "country": "US"}
    }
  ],
  "meta": {"page": 1, "last_page": 3, "total": 5}
}

Contacts are sorted by when they were added, oldest first. Keep asking for the next page until page equals last_page.

phone is in E.164 form or null. sms_consent is none, subscribed (agreed to texts) or unsubscribed (opted out, for example by replying STOP). sms_consent_at and sms_consent_source record when and where the person agreed, and sms_unsubscribed_at when they opted out. postal_address is null when no address is stored. See phone numbers, consent and postal addresses.

email_frequency is all, weekly or monthly, and paused_until is set while the contact paused their emails. Both come from the preference center. unsubscribe_reason is the answer to the question on the unsubscribe page: too_many, not_relevant, never_signed_up, spam, other or null. See the preference center guide.

List interest groups

curl https://mail.example.com/api/v1/audiences/1/interests \
  -H "Authorization: Bearer mr_your_key_here"
{
  "data": [
    {"id": 1, "name": "News", "show_on_form": true, "contacts": 12}
  ]
}

contacts counts contacts of every status who chose the interest.

Add an interest group

Needs the Manager role or higher. The response code is 201.

curl -X POST https://mail.example.com/api/v1/audiences/1/interests \
  -H "Authorization: Bearer mr_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "Offers", "show_on_form": true}'
Field Required Meaning
name Yes Up to 80 characters, unique within the audience.
show_on_form No Whether signup forms show it. Default true.

Create or update a contact

Needs the Manager role or higher. If the email address is not in the audience yet, a contact is created and the response code is 201. Otherwise the existing contact is updated and the code is 200.

For someone who only gave a phone number, send phone without email. The contact gets the status sms_only and is found by that number next time. GET and DELETE on /contacts/{email} also accept the number in E.164 form, encoded for a URL (%2B31612345678). Send whatsapp_consent (none, subscribed or unsubscribed) to record consent for WhatsApp messages.

curl -X PUT https://mail.example.com/api/v1/audiences/1/contacts \
  -H "Authorization: Bearer mr_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"email": "ann@example.com", "first_name": "Ann", "tags": ["customer"]}'
{
  "data": {
    "id": 6,
    "email": "ann@example.com",
    "first_name": "Ann",
    "last_name": null,
    "status": "subscribed",
    "fields": {},
    "tags": ["customer"],
    "source": "api",
    "subscribed_at": "2026-11-18T17:21:53+00:00",
    "created_at": "2026-11-18T17:21:53+00:00"
  }
}
Field Required Meaning
email Yes The contact's email address.
first_name, last_name No Up to 100 characters. Left unchanged when you leave them out.
timezone No The contact's time zone as an IANA name, for example Europe/Amsterdam. Used when a campaign is sent in each contact's time zone.
status No subscribed, pending, unsubscribed, cleaned, archived or transactional (non-subscribed: known, but no marketing email). Sets the status of new and existing contacts.
language No A two-letter language code, such as en or nl. null removes it.
vip No true or false.
status_if_new No The status for a new contact when status is not given. Default pending when the audience uses double opt-in, otherwise subscribed.
fields No Custom field values by merge tag, for example {"birthday": "03-14"}. An empty string removes a value. Other fields stay as they are.
tags No Up to 50 tag names to add. Existing tags are kept.
interests No Interest names, for example ["News", "Offers"]. Replaces the contact's interests; [] removes them all. Left unchanged when you leave it out. An unknown name returns 422.
phone No The mobile number in E.164 form: +, the country code and the number, for example +31612345678. Spaces, dashes, dots, brackets and a leading 00 are accepted and removed. A number without a country code returns 422. null removes the number, and also withdraws consent for texts.
sms_consent No none, subscribed or unsubscribed. subscribed needs a phone number, sent now or stored before.
sms_consent_source No Where the person agreed to texts, for example checkout or pos-signup. Up to 100 letters, digits, spaces and _ . : / -. Only together with "sms_consent": "subscribed". Without it, a new yes gets the source api.
sms_consent_at No When the person agreed, as an ISO 8601 date and time, not in the future. Only together with "sms_consent": "subscribed". Default: now.
postal_address No An object with line1 (street and number, up to 64 characters), line2, city, state, postal_code and country (two letters, such as NL or US). The object replaces the stored address; leave out a part to empty it. null removes the address. Other keys return 422. Markup is removed.

How the status works:

  • Without status, an existing contact keeps their status. This means you can't accidentally resubscribe someone who unsubscribed.
  • "status": "subscribed" for a contact who unsubscribed, bounced (cleaned) or was archived makes them pending and sends the confirmation email. They are subscribed again only once they click it, so a sync that always sends subscribed can't undo unsubscribes.
  • In an audience with double opt-in, new contacts are pending and get the confirmation email unless you send status or status_if_new. They become subscribed when they click it.
  • Addresses on the suppression list never get the confirmation email, and one address gets at most two per audience a day.
  • Setting "status": "pending" on a contact who was not pending also sends the confirmation email.
  • A contact who becomes subscribed through the API starts automations with the "subscribes" trigger, and new tags start automations with the "tag is added" trigger.

Custom field values are checked like on the contact form, but required fields are not enforced.

Recording consent for texts, with proof of where it came from:

curl -X PUT https://mail.example.com/api/v1/audiences/1/contacts \
  -H "Authorization: Bearer mr_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"email": "ann@example.com", "phone": "+31612345678", "sms_consent": "subscribed", "sms_consent_source": "checkout", "sms_consent_at": "2026-10-01T12:00:00+00:00"}'

Only send "sms_consent": "subscribed" when the person agreed to get text messages. An opt-out ("unsubscribed") keeps the time and source of the earlier yes, so you can still show when consent was given.

Get one contact

curl https://mail.example.com/api/v1/audiences/1/contacts/ann@example.com \
  -H "Authorization: Bearer mr_your_key_here"

The response has the same data object as above.

The contact object also has language, vip, engagement (new, rarely, sometimes or often), rating (1 to 5), location (country, region, city, latitude and longitude, or null) and last_changed_at.

Notes and activity

Notes are dated entries your team writes about a contact. Reading needs any role; adding a note needs the Manager role or higher.

curl -X POST https://mail.example.com/api/v1/audiences/1/contacts/ann@example.com/notes \
  -H "Authorization: Bearer mr_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"body": "Called about the invoice."}'
{"data": {"id": 3, "body": "Called about the invoice.", "author": "Sam", "created_at": "2026-11-25T10:02:11+00:00"}}

GET .../notes lists them, newest first. GET .../activity returns the same feed as the contact page: each entry has at, group (email, store, journeys, sms, profile, notes, events or surveys), title, detail and by. Filter with activity[]=email&activity[]=store, from and to (dates as YYYY-MM-DD) and limit (up to 500, default 100).

Delete a contact

Needs the Manager role or higher. This deletes the contact and their history for good.

curl -X DELETE https://mail.example.com/api/v1/audiences/1/contacts/ann@example.com \
  -H "Authorization: Bearer mr_your_key_here"

The response is empty, with code 204.

Add or remove tags

Needs the Manager role or higher.

curl -X POST https://mail.example.com/api/v1/audiences/1/contacts/ann@example.com/tags \
  -H "Authorization: Bearer mr_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"add": ["vip"], "remove": ["customer"]}'
{
  "data": {
    "id": 6,
    "email": "ann@example.com",
    "first_name": "Ann",
    "last_name": "Lee",
    "status": "subscribed",
    "fields": {},
    "tags": ["vip"],
    "source": "api",
    "subscribed_at": "2026-11-18T17:21:53+00:00",
    "created_at": "2026-11-18T17:21:53+00:00"
  }
}

add and remove each take up to 50 tag names of up to 60 characters. Both are optional.

Record a custom event

Needs the Manager role or higher. Use it to tell SendKettle that a contact did something in another system, such as buying something or starting a trial. Automations can start on an event, branch on it, or use it as a goal. See the journey builder guide.

curl -X POST https://mail.example.com/api/v1/events \
  -H "Authorization: Bearer mr_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"audience_id": 1, "email": "ann@example.com", "event": "purchased", "properties": {"order": "A-1001", "total": 49.95}}'
{
  "data": {
    "id": 12,
    "event": "purchased",
    "email": "ann@example.com",
    "properties": {"order": "A-1001", "total": 49.95},
    "created_at": "2026-11-20T09:15:00+00:00"
  }
}

The answer has the code 202.

Field Required Notes
audience_id Yes The audience the contact is in.
email Yes The contact's email address. The contact must already exist, otherwise you get a 404.
event Yes Up to 60 characters: letters, digits, spaces and _ . : -. It must start with a letter or digit.
properties No Up to 30 extra details. Keys are up to 40 characters (letters, digits, _ . -). Values are text up to 500 characters, numbers, true or false. Lists and nested objects are refused.

Segments and snapshots

Live counts of your segments, and snapshots that freeze who was in a segment at one moment. See the segments guide.

Request What it does
GET /audiences/{id}/segments Every segment of the audience with its number of rules, all members (members) and subscribed members (subscribed), counted now.
GET /audiences/{id}/segments/{segment} The same for one segment.
GET /audiences/{id}/segments/{segment}/snapshots The snapshots of a segment: id, name, number of contacts and when it was saved.
POST /audiences/{id}/segments/{segment}/snapshots Saves a snapshot of the subscribed members now. Send an optional name (up to 120 characters). Answers with code 201.
GET /audiences/{id}/segments/{segment}/snapshots/{snapshot} The members of a snapshot: id, email and their status now, 500 per page (per_page up to 1000, page).
curl -X POST https://mail.example.com/api/v1/audiences/1/segments/4/snapshots \
  -H "Authorization: Bearer mr_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "Before the spring sale"}'
{"data": {"id": 7, "segment_id": 4, "name": "Before the spring sale", "contacts": 1280, "created_at": "2026-11-25T09:00:00+00:00"}}

Saving a snapshot and listing its members are written to the audit log.

Journeys

Put contacts in a journey, take them out, move them past a step and see who waits where. Only subscribed contacts of the journey's audience can enter, and only while the journey is on. Listing journeys needs the Viewer role; everything else needs Manager. Putting contacts in and taking them out is written to the audit log.

curl -X POST https://mail.example.com/api/v1/journeys/3/contacts \
  -H "Authorization: Bearer mr_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"email": "ann@example.com"}'
{"data": {"email": "ann@example.com", "status": "active", "step_id": 12, "waiting": true, "next_run_at": "2026-11-27T09:00:00+00:00", "entered_at": "2026-11-25T09:00:00+00:00", "times_entered": 1}, "entered": true}

The answer is 201 when the contact entered and 200 when they were already in the journey (or may not enter again yet). 409 means the journey is off, 422 that the contact is not subscribed and 404 that there is no such contact in the audience.

  • GET /api/v1/journeys lists journeys with their steps (id, type, path and position).
  • GET /api/v1/journeys/{id}/contacts?step_id=12 lists who is in the journey now, optionally only those at one step. Add per_page (up to 500) and page for more.
  • DELETE /api/v1/journeys/{id}/contacts/{email} takes a contact out. The answer is 204.
  • POST /api/v1/journeys/{id}/contacts/{email}/skip moves a contact past the step they wait at. Send {"step_id": 12} to only do this when they are at that step; otherwise the answer is 409.

Ask to hear when a product is back

Needs the Manager role. Records that a subscribed contact wants to know when a store product is back in stock. Journeys that start with A product they asked about is back in stock then take them in once the store reports the product in stock again. Get product ids from the journey editor or the Store page.

curl -X POST https://mail.example.com/api/v1/stock-alerts \
  -H "Authorization: Bearer mr_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"email": "ann@example.com", "audience_id": 1, "product_id": 7}'

List campaigns

curl "https://mail.example.com/api/v1/campaigns?status=sent&per_page=50" \
  -H "Authorization: Bearer mr_your_key_here"
{
  "data": [
    {
      "id": 1,
      "name": "Welcome newsletter",
      "subject": "Hello {{ first_name | there }}!",
      "status": "sent",
      "audience": {"id": 1, "name": "Newsletter"},
      "scheduled_at": null,
      "sent_at": "2026-11-18T10:00:12+01:00",
      "updated_at": "2026-11-18T10:00:12+01:00",
      "kind": "regular",
      "audience_id": 1,
      "folder_id": null,
      "web_url": "https://mail.example.com/c/1/5edde73e0d54cd4a72d6"
    }
  ],
  "meta": {"page": 1, "last_page": 1, "total": 1}
}

Lists campaigns newest first, 50 per page (per_page up to 200). Filter with status (draft, scheduled, sending, testing for a running A/B test, paused, sent or cancelled) and folder_id. kind is regular, or rss for an RSS campaign setup; the emails an RSS campaign sends are regular campaigns. Automation emails are left out. Times are in the account time zone. web_url is the public web version.

Get a campaign report

curl https://mail.example.com/api/v1/campaigns/1/report \
  -H "Authorization: Bearer mr_your_key_here"
{
  "data": {
    "id": 1,
    "recipients": 1200,
    "sent": 1195,
    "opens": 540,
    "clicks": 130,
    "unsubscribes": 4,
    "failed": 5,
    "bounces": 7,
    "complaints": 1,
    "open_rate": 45.2,
    "click_rate": 10.9
  }
}

sent is the number delivered to your provider. opens and clicks count unique readers. The rates are percentages of sent. The reports guide explains each number. The response also has human_opens and human_clicks: opens and clicks without machine opens and scanner clicks.

Get numbers per channel

curl "https://mail.example.com/api/v1/reports/channels?channel=journeys&days=30" \
  -H "Authorization: Bearer mr_your_key_here"
{
  "from": "2026-10-20T00:00:00+00:00",
  "to": "2026-11-19T10:00:00+00:00",
  "data": [
    {"key": "journey:4", "channel": "journeys", "name": "Welcome", "audience": "News", "sent": 120, "delivered": 118, "opens": 70, "open_rate": 58.3, "clicks": 21, "click_rate": 17.5, "unsubscribes": 1, "unsub_rate": 0.83, "bounces": 2, "bounce_rate": 1.67, "complaints": 0, "failed": 0, "orders": 3, "revenue": 8970}
  ],
  "totals": {"sent": 120, "open_rate": 58.3}
}

channel is campaigns, journeys or sms; leave it out for all three. days goes back 1 to 730 days (default 30). There is one row per campaign, per journey or per text message campaign. revenue is in cents. Text messages have sent, delivered and failed only.

Send a one-off email

Needs the Manager role or higher. Use this for transactional emails from your own systems, such as receipts. The email goes straight to your sending provider. It has no footer and is not limited by Max emails per minute. Opens and clicks are tracked unless you send "track_opens": false and "track_clicks": false.

curl -X POST https://mail.example.com/api/v1/messages/send \
  -H "Authorization: Bearer mr_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"to": "ann@example.com", "subject": "Your receipt", "html": "<p>Thanks for your order!</p>", "text": "Thanks for your order!", "reply_to": "support@example.com"}'
{"ok": true, "data": [{"id": "9b2f7c1e-3a4d-4b8e-9f10-2c3d4e5f6a7b", "email": "ann@example.com", "status": "queued", "reject_reason": null, "error": null}]}

The response code is 202, with one result per recipient. When to is one address on the suppression list, the answer is 422.

Field Required Meaning
to Yes One email address, or a list of up to 50.
subject Yes, unless you send template Up to 190 characters.
html Yes, unless you send text or template The HTML body.
text No The plain text body.
from_email, from_name No The sender. Default: the default from email and name in Settings. from_email must be an address you verified on the Domains screen, or use a domain that passed the check there. Any other address returns 422.
reply_to No Where replies go.

Templates, cc and bcc, attachments, inline images, headers, tags, metadata, variables, sending later, the raw MIME endpoint, the message log, the deny and allow lists and the SMTP relay are described in the transactional email guide.

Send a one-off text message

Needs the Manager role or higher. Use this for texts your own systems send, such as a login code or an order update. The text goes out at once, also during quiet hours, but never to a number that replied STOP. You can send 30 texts a minute with one key.

curl -X POST https://mail.example.com/api/v1/sms/send \
  -H "Authorization: Bearer mr_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"to": "+31612345678", "body": "Your code is 123456"}'
{"data": {"id": 41, "to": "+316•••••678", "status": "queued", "segments": 1, "encoding": "GSM-7", "error": null, "sent_at": null, "delivered_at": null}}

The response code is 202. Read the status later with GET /api/v1/sms/41. It changes to sent, delivered, failed or skipped.

Field Required Meaning
to Yes One number in E.164 form, with its country code.
body Yes Up to 1,600 characters.
track_links No true turns links into short links with click counts. Default: false.

A 409 means no SMS provider is set up. A 422 on to means the number is not valid or opted out of texts.

Webhook subscriptions

These endpoints let tools like Zapier subscribe to events. Events are described in the integrations guide, together with the signature on every request.

curl -X POST -H "Authorization: Bearer mr_..." -H "Content-Type: application/json" \
  -d '{"target_url":"https://hooks.zapier.com/hooks/standard/123/abc/","event":"contact.subscribed","audience_id":1}' \
  https://mail.example.com/api/v1/hooks

Response 201:

{"secret": "whsec_...", "id": 5, "event": "contact.subscribed", "target_url": "https://hooks.zapier.com/hooks/standard/123/abc/", "audience_id": 1, "active": true, "created_at": "2026-11-18T09:30:00+00:00"}
Field Required Meaning
target_url Yes Public https address that receives the events. Events contain contact details, so plain http addresses are refused, and so are private and internal ones.
event Yes One event name, for example contact.subscribed.
audience_id No Only send events for this audience.
name No Shown under Integrations.

DELETE /api/v1/hooks/5 answers 204. A key only sees and removes subscriptions made by its own user, and each user can have up to 100. If the receiving address answers 410 Gone, the subscription is removed. ticket.created needs an Admin key, like the support inbox. A subscription only sends while its key exists and its user is still in the workspace with a role that may subscribe to the event: removing someone from the workspace deletes their keys and subscriptions there, and a lower role switches off the subscriptions it may not have.

GET /api/v1/hooks/samples/contact.subscribed answers with a list holding one example delivery, in the same shape as the real thing.

Permissions

Endpoint Lowest role
GET /ping, GET /audiences, GET .../interests, GET .../contacts/{email}, GET .../notes, GET .../activity, GET /campaigns, GET .../report, GET /journeys, GET /reports/channels Viewer
GET /audiences/{id}/contacts, GET /journeys/{id}/contacts Manager
GET /audiences/{id}/segments and one segment, GET .../snapshots Viewer
GET .../snapshots/{snapshot} (the members of a snapshot) Manager
All /hooks endpoints Manager (Admin for ticket.created)
GET /messages, GET /messages/{id}, GET /messages/scheduled, GET /lists/... (lists of addresses) Manager
GET /messages/stats, GET /transactional/templates, GET /transactional/templates/{name} Viewer
PUT, DELETE and POST endpoints Manager, unless the second API guide says otherwise

See the team and roles guide for what each role means.

Errors

Code Meaning Example body
401 The key is missing, wrong, expired or revoked. {"message": "Invalid or missing API key."}
403 Your role does not allow this endpoint. {"message": "Your role does not allow this."}
404 The audience, contact or campaign does not exist. {"message": "No query results for model [App\\Models\\Audience] 99"}
422 The data you sent is not valid. errors lists each problem per field. {"message": "The email field must be a valid email address.", "errors": {"email": ["The email field must be a valid email address."]}}
429 More than 120 requests in a minute, or more than 20 requests with a wrong key from your IP address in a minute (then every key from that address waits a minute). Wait and try again. {"message": "Too Many Attempts."}
409 sms/send only: no SMS provider is set up. {"message": "Set up an SMS provider under Settings first."}
502 messages/send only, and only when the server sends without a queue worker (QUEUE_CONNECTION=sync): your sending provider refused the email. The provider's error is written to the server log, not returned. With a worker the answer is 202 with status queued, and a refusal shows up later as status failed. {"message": "Sending failed. ..."}

If the server runs in debug mode, error bodies also contain technical details. Read only the message and errors keys.

Common problems

Every request returns 401

Check that the header is exactly Authorization: Bearer mr_... with one space after Bearer, and that the key was not revoked.

404 for a contact that exists

Check the audience number, and encode special characters in the email address.

The list of contacts returns 403

Listing contacts needs a Manager key or higher, even though it is a GET request.