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

  1. Klik onderaan het menu op je naam en dan op Profiel om Je profiel te openen.
  2. Typ onder API-sleutels een naam voor de sleutel, bijvoorbeeld "Website".
  3. Kies wanneer hij verloopt: over 30, 90 of 365 dagen, of Geen vervaldatum.
  4. Typ je huidige wachtwoord. Ben je de afgelopen 15 minuten met single sign-on ingelogd, dan is er geen wachtwoordveld.
  5. Klik op Sleutel aanmaken.
  6. 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 status houdt 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 contact pending en stuurt de bevestigingsmail. Het is pas weer aangemeld na een klik erop, zodat een koppeling die altijd subscribed stuurt geen afmeldingen ongedaan kan maken.
  • In een doelgroep met dubbele opt-in zijn nieuwe contacten pending en krijgen ze de bevestigingsmail, tenzij je status of status_if_new meestuurt. 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/journeys toont de trajecten met hun stappen (id, type, pad en positie).
  • GET /api/v1/journeys/{id}/contacts?step_id=12 toont wie nu in het traject zit, eventueel alleen bij één stap. Voeg per_page (tot 500) en page toe voor meer.
  • DELETE /api/v1/journeys/{id}/contacts/{email} haalt een contact eruit. Het antwoord is 204.
  • POST /api/v1/journeys/{id}/contacts/{email}/skip zet 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 antwoord 409.

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.