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
- Click your name at the bottom of the menu and then Profile to open Your profile.
- Under API keys, type a name for the key, for example "Website".
- Choose when it expires: in 30, 90 or 365 days, or No expiry date.
- Type your current password. If you logged in with single sign-on in the last 15 minutes, there is no password box.
- Click Create key.
- 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 thempendingand sends the confirmation email. They are subscribed again only once they click it, so a sync that always sendssubscribedcan't undo unsubscribes.- In an audience with double opt-in, new contacts are
pendingand get the confirmation email unless you sendstatusorstatus_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/journeyslists journeys with their steps (id, type, path and position).GET /api/v1/journeys/{id}/contacts?step_id=12lists who is in the journey now, optionally only those at one step. Addper_page(up to 500) andpagefor more.DELETE /api/v1/journeys/{id}/contacts/{email}takes a contact out. The answer is204.POST /api/v1/journeys/{id}/contacts/{email}/skipmoves 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 is409.
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.