API
Met de API praten je website, winkel of andere programma's met SendKettle. Je kunt contacten toevoegen en bijwerken, hun tags wijzigen, campagnes en rapporten lezen, en losse e-mails versturen, zoals bonnetjes.
Alle verzoeken en antwoorden gebruiken JSON. De voorbeelden gebruiken https://mail.example.com als adres van je SendKettle. Vervang dat door het jouwe. De API antwoordt altijd in het Engels.
Deze handleiding behandelt sleutels, contacten, tags, events, trajecten, rapporten en webhook-abonnementen. Campagnes maken en versturen, details van rapporten, velden en segmenten van een doelgroep, batches, sjablonen, bestanden, landingspagina's, sms, zoeken, contacten vergeten, exports, apps die via OAuth koppelen en de OpenAPI-beschrijving staan in API: campagnes, rapporten, batches en apps.
Een API-sleutel aanmaken
- Klik onderaan het menu op je naam en dan op Profiel om Je profiel te openen.
- Typ onder API-sleutels een naam voor de sleutel, bijvoorbeeld "Website".
- Kies wanneer hij verloopt: over 30, 90 of 365 dagen, of Geen vervaldatum.
- Typ je huidige wachtwoord. Ben je de afgelopen 15 minuten met single sign-on ingelogd, dan is er geen wachtwoordveld.
- Klik op Sleutel aanmaken.
- Kopieer de sleutel meteen uit Je nieuwe sleutel. Hij begint met
mr_en wordt maar één keer getoond.
De lijst toont van elke sleutel de naam, de eerste tekens, wanneer hij voor het laatst is gebruikt en wanneer hij verloopt. Klik op Intrekken om een sleutel te verwijderen. Verzoeken met die sleutel werken dan meteen niet meer.
Elke keer dat er een sleutel op je account wordt gemaakt, krijg je een e-mail met de naam, de eerste tekens en wanneer hij verloopt (nooit de sleutel zelf). Heb je hem niet zelf gemaakt, trek hem dan in, wijzig je wachtwoord en laat het een beheerder weten. Beheerders en Eigenaren zien de sleutels van het hele team onder Instellingen, Team, API-sleutels en kunnen ze daar intrekken. Je krijgt een e-mail als ze een van jouw sleutels intrekken (zie Team en rollen).
Je sleutels worden vanzelf ingetrokken als je je wachtwoord wijzigt of opnieuw instelt, of tweestapsverificatie aan- of uitzet. Een sleutel die iemand met een gestolen wachtwoord of sessie maakte, werkt dan niet meer zodra je dat herstelt. Maak daarna nieuwe sleutels. Zolang je team tweestapsverificatie vereist, krijgen sleutels van mensen die het niet hebben ingesteld 403 (accounts met single sign-on uitgezonderd).
Een sleutel werkt namens jou, met jouw rol. Hij hoort bij de werkruimte waarin je zat toen je hem maakte en ziet alleen de lijsten, contacten en campagnes van die werkruimte. Maak dus een sleutel in elke werkruimte die je wilt bereiken (zie Werkruimtes). De sleutel van een Lezer kan alleen lezen. Voor de meeste acties die iets wijzigen heb je een sleutel van een Manager of hoger nodig (zie rechten). Houd sleutels geheim: iedereen met een sleutel kan doen wat jij kunt.
Authenticatie
Stuur de sleutel mee in de header Authorization van elk verzoek:
curl https://mail.example.com/api/v1/ping \
-H "Authorization: Bearer mr_your_key_here" \
-H "Accept: application/json"
Voeg Content-Type: application/json toe aan verzoeken met inhoud.
Grenzen
Je kunt 120 verzoeken per minuut doen. Elk antwoord heeft een header X-RateLimit-Remaining met het aantal dat je nog over hebt.
Endpoints
| Methode | Pad | Wat het doet |
|---|---|---|
| GET | /api/v1/ping |
Je sleutel controleren. |
| GET | /api/v1/audiences |
Doelgroepen tonen met hun eigen velden en interesses. |
| GET | /api/v1/audiences/{id}/interests |
De interessegroepen van een doelgroep tonen. |
| POST | /api/v1/audiences/{id}/interests |
Een interessegroep toevoegen. |
| GET | /api/v1/audiences/{id}/contacts |
Contacten van een doelgroep tonen. |
| PUT | /api/v1/audiences/{id}/contacts |
Een contact op e-mailadres aanmaken of bijwerken. |
| GET | /api/v1/audiences/{id}/contacts/{email} |
Eén contact ophalen. |
| DELETE | /api/v1/audiences/{id}/contacts/{email} |
Eén contact verwijderen. |
| POST | /api/v1/audiences/{id}/contacts/{email}/tags |
Tags toevoegen of weghalen. |
| GET | /api/v1/audiences/{id}/contacts/{email}/notes |
De notities van een contact tonen. |
| POST | /api/v1/audiences/{id}/contacts/{email}/notes |
Een notitie toevoegen. |
| GET | /api/v1/audiences/{id}/contacts/{email}/activity |
De activiteit van een contact, nieuwste eerst. |
| POST | /api/v1/events |
Een eigen event voor een contact vastleggen. |
| GET | /api/v1/journeys |
Trajecten en hun stappen tonen. |
| GET | /api/v1/journeys/{id}/contacts |
Tonen wie nu in een traject zit. |
| POST | /api/v1/journeys/{id}/contacts |
Een contact in een traject zetten. |
| DELETE | /api/v1/journeys/{id}/contacts/{email} |
Een contact uit een traject halen. |
| POST | /api/v1/journeys/{id}/contacts/{email}/skip |
Een contact voorbij de stap zetten waar het wacht. |
| POST | /api/v1/stock-alerts |
Vragen om een melding als een product weer op voorraad is. |
| GET | /api/v1/campaigns |
Campagnes tonen. Meer endpoints voor campagnes staan in de tweede API-handleiding. |
| GET | /api/v1/campaigns/{id}/report |
De getallen van een campagne ophalen. |
| GET | /api/v1/reports/channels |
Getallen per campagne, journey of sms-bericht over een periode. |
| POST | /api/v1/messages/send |
Een transactionele e-mail versturen (aan een of meer ontvangers, of met een sjabloon). |
| POST | /api/v1/messages/send-raw |
Een volledig MIME-bericht versturen. |
| GET | /api/v1/messages |
Het logboek van transactionele berichten doorzoeken. |
| GET | /api/v1/messages/{id} |
Eén bericht met zijn geschiedenis en inhoud. |
| GET | /api/v1/messages/scheduled |
Ingeplande berichten en berichten in de wachtrij. |
| POST | /api/v1/messages/{id}/cancel |
Een ingepland bericht of een bericht in de wachtrij annuleren. |
| POST | /api/v1/messages/{id}/reschedule |
Een ingepland bericht naar een ander tijdstip verplaatsen. |
| GET | /api/v1/messages/stats |
Cijfers van transactionele e-mail per dag. |
| GET | /api/v1/transactional/templates |
Transactionele sjablonen tonen. |
| GET, PUT, DELETE | /api/v1/transactional/templates/{name} |
Een sjabloon ophalen, aanmaken of bijwerken, of verwijderen. |
| POST | /api/v1/transactional/templates/{name}/publish |
Het concept van een sjabloon publiceren. |
| POST | /api/v1/transactional/templates/{name}/render |
Een sjabloon met variabelen invullen zonder te versturen. |
| GET, POST | /api/v1/lists/{deny of allow} |
De blokkeer- of toestaanlijst tonen of aanvullen. |
| DELETE | /api/v1/lists/{deny of allow}/{entry} |
Een regel van de lijst halen. |
| POST | /api/v1/sms/send |
Een losse sms versturen. |
| GET | /api/v1/sms/{id} |
De status van een losse sms ophalen. |
| GET | /api/v1/hooks |
Je webhook-abonnementen tonen. |
| POST | /api/v1/hooks |
Een adres abonneren op een event (gebruikt door Zapier). |
| DELETE | /api/v1/hooks/{id} |
Een abonnement weghalen. |
| GET | /api/v1/hooks/events |
De events tonen waarop je kunt abonneren. |
| GET | /api/v1/hooks/samples/{event} |
Voorbeeldgegevens voor een event. |
{id} is het nummer van de doelgroep of campagne. De nummers van doelgroepen haal je op met GET /api/v1/audiences. {email} is het e-mailadres van het contact. Codeer het voor een URL als er speciale tekens in staan. Een + wordt bijvoorbeeld %2B.
Webwinkels sturen klanten, producten, bestellingen, winkelwagens, promotiecodes en surfgedrag via de endpoints onder /api/v1/store. Die hebben een eigen handleiding: Winkel-API.
Je sleutel controleren
curl https://mail.example.com/api/v1/ping \
-H "Authorization: Bearer mr_your_key_here"
{"ok": true, "user": "admin@example.com", "role": "owner"}
Doelgroepen tonen
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 telt contacten van elke status.
Contacten tonen
Hiervoor heb je de rol Manager of hoger nodig, omdat het werkt als een 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"
| Queryparameter | Betekenis |
|---|---|
status |
Optioneel. Alleen contacten met deze status: subscribed, pending, unsubscribed of cleaned. |
per_page |
Optioneel. 1 tot 1000, standaard 100. |
page |
Optioneel. Paginanummer, standaard 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}
}
Contacten staan op volgorde van toevoegen, oudste eerst. Vraag steeds de volgende pagina op tot page gelijk is aan last_page.
phone staat in E.164-vorm of is null. sms_consent is none, subscribed (stemde in met sms-berichten) of unsubscribed (meldde zich af, bijvoorbeeld door STOP te antwoorden). sms_consent_at en sms_consent_source leggen vast wanneer en waar de persoon instemde, en sms_unsubscribed_at wanneer die zich afmeldde. postal_address is null als er geen adres is opgeslagen. Zie telefoonnummers, toestemming en postadressen.
email_frequency is all, weekly of monthly, en paused_until is ingevuld zolang het contact de e-mails heeft gepauzeerd. Beide komen uit het voorkeurencentrum. unsubscribe_reason is het antwoord op de vraag op de afmeldpagina: too_many, not_relevant, never_signed_up, spam, other of null. Zie de handleiding over het voorkeurencentrum.
Interessegroepen tonen
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 telt contacten van elke status die de interesse kozen.
Een interessegroep toevoegen
Hiervoor heb je de rol Manager of hoger nodig. De antwoordcode 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}'
| Veld | Verplicht | Betekenis |
|---|---|---|
name |
Ja | Tot 80 tekens, uniek binnen de doelgroep. |
show_on_form |
Nee | Of aanmeldformulieren hem tonen. Standaard true. |
Een contact aanmaken of bijwerken
Hiervoor heb je de rol Manager of hoger nodig. Staat het e-mailadres nog niet in de doelgroep, dan wordt er een contact aangemaakt en is de antwoordcode 201. Anders wordt het bestaande contact bijgewerkt en is de code 200.
Voor iemand die alleen een telefoonnummer gaf, stuur je phone zonder email. Het contact krijgt de status sms_only en wordt de volgende keer op dat nummer gevonden. GET en DELETE op /contacts/{email} accepteren ook het nummer in E.164-vorm, gecodeerd voor een URL (%2B31612345678). Stuur whatsapp_consent (none, subscribed of unsubscribed) mee om toestemming voor WhatsApp-berichten vast te leggen.
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"
}
}
| Veld | Verplicht | Betekenis |
|---|---|---|
email |
Ja | Het e-mailadres van het contact. |
first_name, last_name |
Nee | Tot 100 tekens. Blijven ongewijzigd als je ze weglaat. |
timezone |
Nee | De tijdzone van het contact als IANA-naam, bijvoorbeeld Europe/Amsterdam. Wordt gebruikt als een campagne in de tijdzone van elk contact wordt verstuurd. |
status |
Nee | subscribed, pending, unsubscribed of cleaned. Zet de status van nieuwe en bestaande contacten. |
status_if_new |
Nee | De status voor een nieuw contact als status ontbreekt. Standaard pending als de doelgroep dubbele opt-in gebruikt, anders subscribed. |
fields |
Nee | Waarden van eigen velden per samenvoegtag, bijvoorbeeld {"birthday": "03-14"}. Een lege tekst haalt een waarde weg. Andere velden blijven zoals ze zijn. |
tags |
Nee | Tot 50 namen van tags om toe te voegen. Bestaande tags blijven staan. |
interests |
Nee | Namen van interesses, bijvoorbeeld ["News", "Offers"]. Vervangt de interesses van het contact. [] haalt ze allemaal weg. Blijft ongewijzigd als je het weglaat. Een onbekende naam geeft 422. |
phone |
Nee | Het mobiele nummer in E.164-vorm: +, de landcode en het nummer, bijvoorbeeld +31612345678. Spaties, streepjes, punten, haakjes en een 00 aan het begin worden geaccepteerd en weggehaald. Een nummer zonder landcode geeft 422. null haalt het nummer weg en trekt ook de toestemming voor sms-berichten in. |
sms_consent |
Nee | none, subscribed of unsubscribed. subscribed heeft een telefoonnummer nodig, nu meegestuurd of eerder opgeslagen. |
sms_consent_source |
Nee | Waar de persoon instemde met sms-berichten, bijvoorbeeld checkout of pos-signup. Tot 100 letters, cijfers, spaties en _ . : / -. Alleen samen met "sms_consent": "subscribed". Zonder deze waarde krijgt een nieuwe toestemming de bron api. |
sms_consent_at |
Nee | Wanneer de persoon instemde, als ISO 8601-datum en -tijd, niet in de toekomst. Alleen samen met "sms_consent": "subscribed". Standaard: nu. |
postal_address |
Nee | Een object met line1 (straat en huisnummer, tot 64 tekens), line2, city, state, postal_code en country (twee letters, zoals NL of US). Het object vervangt het opgeslagen adres; laat je een deel weg, dan wordt het leeg. null haalt het adres weg. Andere sleutels geven 422. Opmaak wordt weggehaald. |
Zo werkt de status:
- Zonder
statushoudt een bestaand contact zijn status. Zo meld je nooit per ongeluk iemand opnieuw aan die zich afmeldde. "status": "subscribed"bij een contact dat zich afmeldde, bouncete (cleaned) of gearchiveerd is, maakt het contactpendingen stuurt de bevestigingsmail. Het is pas weer aangemeld na een klik erop, zodat een koppeling die altijdsubscribedstuurt geen afmeldingen ongedaan kan maken.- In een doelgroep met dubbele opt-in zijn nieuwe contacten
pendingen krijgen ze de bevestigingsmail, tenzij jestatusofstatus_if_newmeestuurt. Ze worden aangemeld als ze erop klikken. - Adressen op de onderdrukkingslijst krijgen nooit de bevestigingsmail, en één adres krijgt er hoogstens twee per doelgroep per dag.
- Zet je
"status": "pending"bij een contact dat nog niet in afwachting was, dan gaat de bevestigingsmail ook weg. - Een contact dat via de API aangemeld wordt, start automatiseringen met de trigger voor aanmelden, en nieuwe tags starten automatiseringen met de trigger voor een toegevoegde tag.
Waarden van eigen velden worden gecontroleerd zoals op het formulier voor contacten, maar verplichte velden worden niet afgedwongen.
Toestemming voor sms-berichten vastleggen, met bewijs van waar die vandaan kwam:
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"}'
Stuur alleen "sms_consent": "subscribed" als iemand akkoord ging met sms-berichten. Een afmelding ("unsubscribed") bewaart de tijd en bron van het eerdere ja, zodat je nog steeds kunt laten zien wanneer de toestemming is gegeven.
Eén contact ophalen
curl https://mail.example.com/api/v1/audiences/1/contacts/ann@example.com \
-H "Authorization: Bearer mr_your_key_here"
Het antwoord heeft hetzelfde object data als hierboven.
Het contactobject heeft ook language, vip, engagement (new, rarely, sometimes of often), rating (1 tot 5), location (country, region, city, latitude en longitude, of null) en last_changed_at.
Notities en activiteit
Notities zijn gedateerde regels die je team over een contact schrijft. Lezen kan met elke rol; een notitie toevoegen vraagt de rol Manager of hoger.
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": "Gebeld over de factuur."}'
{"data": {"id": 3, "body": "Gebeld over de factuur.", "author": "Sam", "created_at": "2026-11-25T10:02:11+00:00"}}
GET .../notes toont ze, nieuwste eerst. GET .../activity geeft hetzelfde overzicht als de pagina van het contact: elke regel heeft at, group (email, store, journeys, sms, profile, notes, events of surveys), title, detail en by. Filter met activity[]=email&activity[]=store, from en to (datums als YYYY-MM-DD) en limit (tot 500, standaard 100).
Een contact verwijderen
Hiervoor heb je de rol Manager of hoger nodig. Dit verwijdert het contact en de geschiedenis voorgoed.
curl -X DELETE https://mail.example.com/api/v1/audiences/1/contacts/ann@example.com \
-H "Authorization: Bearer mr_your_key_here"
Het antwoord is leeg, met code 204.
Tags toevoegen of weghalen
Hiervoor heb je de rol Manager of hoger nodig.
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 en remove nemen elk tot 50 namen van tags van tot 60 tekens. Beide zijn optioneel.
Een eigen event vastleggen
Hiervoor heb je de rol Manager of hoger nodig. Hiermee vertel je SendKettle dat een contact iets deed in een ander systeem, zoals iets kopen of een proefperiode beginnen. Automatiseringen kunnen op een event beginnen, erop vertakken of het als doel gebruiken. Zie de handleiding over trajecten.
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"
}
}
Het antwoord heeft de code 202.
| Veld | Verplicht | Opmerkingen |
|---|---|---|
audience_id |
Ja | De doelgroep waarin het contact staat. |
email |
Ja | Het e-mailadres van het contact. Het contact moet al bestaan, anders krijg je een 404. |
event |
Ja | Tot 60 tekens: letters, cijfers, spaties en _ . : -. Het moet beginnen met een letter of cijfer. |
properties |
Nee | Tot 30 extra details. Sleutels zijn tot 40 tekens (letters, cijfers, _ . -). Waarden zijn tekst tot 500 tekens, getallen, true of false. Lijsten en geneste objecten worden geweigerd. |
Segmenten en momentopnamen
Actuele aantallen van je segmenten, en momentopnamen die vastleggen wie er op één moment in een segment zat. Zie de handleiding over segmenten.
| Verzoek | Wat het doet |
|---|---|
GET /audiences/{id}/segments |
Alle segmenten van de doelgroep met het aantal regels, alle leden (members) en de ingeschreven leden (subscribed), nu geteld. |
GET /audiences/{id}/segments/{segment} |
Hetzelfde voor één segment. |
GET /audiences/{id}/segments/{segment}/snapshots |
De momentopnamen van een segment: id, naam, aantal contacten en wanneer hij is opgeslagen. |
POST /audiences/{id}/segments/{segment}/snapshots |
Slaat nu een momentopname van de ingeschreven leden op. Stuur eventueel een name mee (hoogstens 120 tekens). Antwoordt met code 201. |
GET /audiences/{id}/segments/{segment}/snapshots/{snapshot} |
De leden van een momentopname: id, email en hun status nu, 500 per pagina (per_page tot 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": "Voor de voorjaarsuitverkoop"}'
{"data": {"id": 7, "segment_id": 4, "name": "Voor de voorjaarsuitverkoop", "contacts": 1280, "created_at": "2026-11-25T09:00:00+00:00"}}
Het opslaan van een momentopname en het opvragen van de leden komen in het auditlogboek.
Trajecten
Contacten in een traject zetten, eruit halen, voorbij een stap zetten en zien wie waar wacht. Alleen aangemelde contacten van de doelgroep van het traject kunnen erin, en alleen als het traject aan staat. Trajecten opvragen kan met de rol Lezer; al het andere vraagt Manager. Contacten erin zetten en eruit halen komt in het auditlogboek.
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}
Het antwoord is 201 als het contact instroomde en 200 als het al in het traject zat (of nog niet opnieuw mag instromen). 409 betekent dat het traject uit staat, 422 dat het contact niet is aangemeld en 404 dat dat contact niet in de doelgroep zit.
GET /api/v1/journeystoont de trajecten met hun stappen (id, type, pad en positie).GET /api/v1/journeys/{id}/contacts?step_id=12toont wie nu in het traject zit, eventueel alleen bij één stap. Voegper_page(tot 500) enpagetoe voor meer.DELETE /api/v1/journeys/{id}/contacts/{email}haalt een contact eruit. Het antwoord is204.POST /api/v1/journeys/{id}/contacts/{email}/skipzet een contact voorbij de stap waar het wacht. Stuur{"step_id": 12}om dat alleen te doen als het bij die stap staat; anders is het antwoord409.
Vragen om een melding als een product terug is
Vraagt de rol Manager. Legt vast dat een aangemeld contact wil weten wanneer een product uit de winkel weer op voorraad is. Trajecten die beginnen met Een product waar ze naar vroegen is weer op voorraad nemen het contact op zodra de winkel het product weer op voorraad meldt. De product-id's vind je in de trajecteditor of op de pagina Winkel.
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}'
Campagnes tonen
curl "https://mail.example.com/api/v1/campaigns?status=sent&per_page=50" \
-H "Authorization: Bearer mr_your_key_here"
{
"data": [
{
"id": 1,
"name": "Welkomstnieuwsbrief",
"subject": "Hallo {{ first_name | daar }}!",
"status": "sent",
"audience": {"id": 1, "name": "Nieuwsbrief"},
"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}
}
Toont campagnes, nieuwste eerst, 50 per pagina (per_page tot 200). Filter met status (draft, scheduled, sending, testing voor een lopende A/B-test, paused, sent of cancelled) en folder_id. kind is regular, of rss voor de instelling van een RSS-campagne; de e-mails die een RSS-campagne verstuurt zijn gewone campagnes. E-mails van automatiseringen worden weggelaten. Tijden staan in de tijdzone van het account. web_url is de openbare webversie.
Een rapport van een campagne ophalen
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 het aantal dat aan je provider is gegeven. opens en clicks tellen unieke lezers. De ratio's zijn percentages van sent. De handleiding over rapporten legt elk getal uit. Het antwoord heeft ook human_opens en human_clicks: opens en klikken zonder machine-opens en scannerklikken.
Getallen per kanaal ophalen
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 of sms; laat het weg voor alle drie. days gaat 1 tot 730 dagen terug (standaard 30). Er is één rij per campagne, per journey of per sms-campagne. revenue is in centen. Sms-berichten hebben alleen sent, delivered en failed.
Een losse e-mail versturen
Hiervoor heb je de rol Manager of hoger nodig. Gebruik dit voor transactionele e-mails uit je eigen systemen, zoals bonnetjes. De e-mail gaat rechtstreeks naar je verzendprovider. Hij heeft geen footer en valt niet onder Max. e-mails per minuut. Opens en kliks worden gemeten, tenzij je "track_opens": false en "track_clicks": false meestuurt.
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}]}
De antwoordcode is 202, met één resultaat per ontvanger. Is to één adres op de onderdrukkingslijst, dan is het antwoord 422.
| Veld | Verplicht | Betekenis |
|---|---|---|
to |
Ja | Eén e-mailadres, of een lijst van tot 50. |
subject |
Ja, tenzij je template stuurt |
Tot 190 tekens. |
html |
Ja, tenzij je text of template stuurt |
De inhoud in HTML. |
text |
Nee | De inhoud in platte tekst. |
from_email, from_name |
Nee | De afzender. Standaard: het standaard afzenderadres en de standaard afzendernaam in Instellingen. from_email moet een adres zijn dat je op het scherm Domeinen hebt geverifieerd, of een domein gebruiken dat daar de controle doorstond. Elk ander adres geeft 422. |
reply_to |
Nee | Waar antwoorden naartoe gaan. |
Sjablonen, cc en bcc, bijlagen, afbeeldingen in de tekst, headers, tags, metadata, variabelen, later versturen, het endpoint voor ruwe MIME-berichten, het berichtenlogboek, de blokkeer- en toestaanlijst en de SMTP-relay staan in de handleiding over transactionele e-mail.
Een losse sms versturen
Hiervoor heb je minstens de rol Manager nodig. Gebruik dit voor sms'jes die je eigen systemen sturen, zoals een inlogcode of een update over een bestelling. De sms gaat meteen weg, ook tijdens stille uren, maar nooit naar een nummer dat STOP antwoordde. Met één sleutel kun je 30 sms'jes per minuut sturen.
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": "Je code is 123456"}'
{"data": {"id": 41, "to": "+316•••••678", "status": "queued", "segments": 1, "encoding": "GSM-7", "error": null, "sent_at": null, "delivered_at": null}}
De antwoordcode is 202. Lees de status later met GET /api/v1/sms/41. Die verandert in sent, delivered, failed of skipped.
| Veld | Verplicht | Betekenis |
|---|---|---|
to |
Ja | Eén nummer in E.164-vorm, met landcode. |
body |
Ja | Tot 1.600 tekens. |
track_links |
Nee | true maakt van links korte links met klikken. Standaard: false. |
Een 409 betekent dat er geen sms-provider is ingesteld. Een 422 op to betekent dat het nummer niet geldig is of zich afmeldde voor sms.
Webhook-abonnementen
Met deze endpoints abonneren programma's zoals Zapier zich op events. De events staan beschreven in de handleiding over koppelingen, samen met de handtekening op elk verzoek.
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
Antwoord 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"}
| Veld | Verplicht | Betekenis |
|---|---|---|
target_url |
Ja | Openbaar https-adres dat de events ontvangt. Events bevatten contactgegevens, dus gewone http-adressen worden geweigerd, net als privé- en interne adressen. |
event |
Ja | Eén naam van een event, bijvoorbeeld contact.subscribed. |
audience_id |
Nee | Alleen events voor deze doelgroep sturen. |
name |
Nee | Getoond onder Koppelingen. |
DELETE /api/v1/hooks/5 antwoordt 204. Een sleutel ziet alleen abonnementen van de eigen gebruiker en kan alleen die weghalen. Elke gebruiker kan er tot 100 hebben. Antwoordt het ontvangende adres met 410 Gone, dan wordt het abonnement weggehaald. Voor ticket.created is een sleutel van een Beheerder nodig, net als voor de support-inbox. Een abonnement verstuurt alleen zolang de sleutel bestaat en de gebruiker nog in de werkruimte zit, met een rol die zich op de gebeurtenis mag abonneren: wie uit de werkruimte wordt gehaald, verliest daar zijn sleutels en abonnementen, en een lagere rol zet de abonnementen uit die hij niet mag hebben.
GET /api/v1/hooks/samples/contact.subscribed antwoordt met een lijst met één voorbeeld van een aflevering, in dezelfde vorm als het echte bericht.
Rechten
| Endpoint | Laagste rol |
|---|---|
GET /ping, GET /audiences, GET .../interests, GET .../contacts/{email}, GET .../notes, GET .../activity, GET /campaigns, GET .../report, GET /journeys, GET /reports/channels |
Lezer |
GET /audiences/{id}/contacts, GET /journeys/{id}/contacts |
Manager |
GET /audiences/{id}/segments en één segment, GET .../snapshots |
Lezer |
GET .../snapshots/{snapshot} (de leden van een momentopname) |
Manager |
Alle endpoints onder /hooks |
Manager (Beheerder voor ticket.created) |
GET /messages, GET /messages/{id}, GET /messages/scheduled, GET /lists/... (lijsten met adressen) |
Manager |
GET /messages/stats, GET /transactional/templates, GET /transactional/templates/{name} |
Lezer |
Endpoints met PUT, DELETE en POST |
Manager, tenzij de tweede API-handleiding iets anders zegt |
Zie de handleiding over team en rollen voor wat elke rol betekent.
Fouten
| Code | Betekenis | Voorbeeld van de inhoud |
|---|---|---|
401 |
De sleutel ontbreekt, klopt niet, is verlopen of is ingetrokken. | {"message": "Invalid or missing API key."} |
403 |
Je rol staat dit endpoint niet toe. | {"message": "Your role does not allow this."} |
404 |
De doelgroep, het contact of de campagne bestaat niet. | {"message": "No query results for model [App\\Models\\Audience] 99"} |
422 |
De gegevens die je stuurde zijn niet geldig. errors noemt elk probleem per veld. |
{"message": "The email field must be a valid email address.", "errors": {"email": ["The email field must be a valid email address."]}} |
429 |
Meer dan 120 verzoeken in een minuut, of meer dan 20 verzoeken met een verkeerde sleutel vanaf je IP-adres in een minuut (dan wacht elke sleutel vanaf dat adres een minuut). Wacht en probeer het opnieuw. | {"message": "Too Many Attempts."} |
409 |
Alleen bij sms/send: er is geen sms-provider ingesteld. |
{"message": "Set up an SMS provider under Settings first."} |
502 |
Alleen bij messages/send, en alleen als de server zonder queue-worker verstuurt (QUEUE_CONNECTION=sync): je verzendprovider weigerde de e-mail. De fout van de provider staat in het serverlog en wordt niet teruggestuurd. Met een worker is het antwoord 202 met status queued, en een weigering zie je later als status failed. |
{"message": "Sending failed. ..."} |
Draait de server in debugmodus, dan bevat de inhoud van fouten ook technische details. Lees alleen de sleutels message en errors.
Veelvoorkomende problemen
Elk verzoek geeft 401
Kijk of de header precies Authorization: Bearer mr_... is, met één spatie na Bearer, en of de sleutel niet is ingetrokken.
404 voor een contact dat bestaat
Controleer het nummer van de doelgroep, en codeer speciale tekens in het e-mailadres.
De lijst met contacten geeft 403
Contacten tonen vraagt om een sleutel van een Manager of hoger, ook al is het een GET-verzoek.