API voor aanmeldingen
Abonnees aanmelden vanaf je eigen website of systeem, bijvoorbeeld met een vinkje bij een boeking.
Met de API meldt je eigen website mensen aan op een lijst, vanaf je server. Denk aan een boekings- of offerteformulier met een vinkje "Houd me op de hoogte". Staat het vinkje aan, dan geeft je site het e-mailadres door aan BandPage, en wij zorgen voor de bevestiging, de afmeldlink en de rest.
De API hoort bij een betaald abonnement. Dit onderwerp is geschreven voor de ontwikkelaar die de koppeling bouwt.
Een token aanmaken#
- Open API in het menu onder Nieuwsbrief.
- Druk op Token aanmaken, geef het token een naam (bijvoorbeeld "boekingsformulier") en kies de lijsten waarop het mag aanmelden.
- Kopieer het token meteen. Je ziet het maar één keer: wij bewaren alleen een versleutelde versie.
In hetzelfde venster staan de basis-URL en het lijst-id van elke gekozen lijst. Meer heeft je site niet nodig.
Een token kan alleen aanmelden op de lijsten die je erbij kiest. Gebruik per website of systeem een eigen token, zodat je er één kunt intrekken zonder de andere te raken. Intrekken doe je met Intrekken in de tabel met tokens. Een website die een ingetrokken token gebruikt, krijgt daarna een foutmelding.
Bewaar het token alleen op je server. Zet het nooit in JavaScript of HTML die een bezoeker kan zien.
Verzoeken#
- Alleen via HTTPS.
- Stuur het token mee als
Authorization: Bearer <token>. - Stuur
Content-Type: application/jsonenAccept: application/json. - Antwoorden zijn altijd JSON.
Iemand aanmelden#
POST /lists/{lijst-id}/subscribers, achter de basis-URL.
| Veld | Type | Verplicht | Toelichting |
|---|---|---|---|
email |
tekst | ja | Het e-mailadres, maximaal 255 tekens. Hoofdletters maken niet uit. |
first_name |
tekst | nee | Voornaam, maximaal 255 tekens. Overschrijft geen naam die we al hebben. |
last_name |
tekst | nee | Achternaam, maximaal 255 tekens. |
locale |
nl of en |
nee | Taal van de bevestigingsmail. Zonder dit veld de taal van je pagina. |
source |
tekst | nee | Korte herkomst, bijvoorbeeld booking-form. Maximaal 64 tekens. |
reference |
tekst | nee | Je eigen referentie, bijvoorbeeld het nummer van de boeking. Maximaal 100 tekens. |
consented_at |
datum en tijd | nee | Wanneer het vinkje werd aangezet, in ISO 8601, zoals 2026-11-17T10:15:00+01:00. |
consent_text |
tekst | nee | De zin die bij het vinkje stond. Maximaal 1000 tekens. |
confirmation |
email, link of none |
nee | Hoe de aanmelding bevestigd wordt, zie hieronder. Standaard email. |
Stuur source, reference, consented_at en consent_text mee als je ze hebt. Daarmee kun je later aantonen wanneer en waarmee iemand toestemming gaf. Je ziet ze terug bij het contact en in de export.
Het antwoord heeft altijd een status en een subscriber_id:
| HTTP | status |
Betekenis |
|---|---|---|
| 201 | pending |
Nieuw adres. Er is een bevestigingsmail verstuurd. |
| 200 | pending |
Er was al eerder om bevestiging gevraagd. Er gaat alleen een nieuwe mail uit als dat mag (zie hieronder). |
| 200 | already_subscribed |
Staat al op de lijst. Er gaat niets uit. |
| 200 | resubscribe_pending |
Had zich afgemeld en meldt zich opnieuw aan. Er is een bevestigingsmail verstuurd. |
| 200 | suppressed |
Het adres is geblokkeerd. Er gaat niets uit en er verandert niets. Zie Geblokkeerde adressen. |
{ "status": "pending", "subscriber_id": null }
subscriber_id is ons id van het contact. Het is null zolang het adres niet bevestigd is, want tot de klik op de bevestigingslink slaan we het adres niet op.
Bevestiging#
Standaard krijgt de aanmelder een bevestigingsmail van je afzender, met een link. Die link opent een pagina met een knop Aanmelding bevestigen, en pas na een druk op die knop staat hij op de lijst. Het openen van de link alleen is niet genoeg, want veel zakelijke mailservers openen elke link in een mail om hem op virussen te controleren, nog voordat de ontvanger de mail ziet. Zo weet je zeker dat het adres klopt en dat de eigenaar het zelf wilde. Het veld confirmation geeft je twee andere mogelijkheden.
confirmation: "link": de knop in je eigen mail. Wij sturen dan niets, maar je krijgt de bevestigingslink terug in confirmation_url. Zet die als knop in een mail die je toch al stuurt, zoals de bevestiging van een boeking. Je klant krijgt dan één mail in plaats van twee, en het blijft een echte dubbele bevestiging: de link opent dezelfde pagina met de bevestigknop. De link is 30 dagen geldig.
{ "status": "pending", "subscriber_id": null, "confirmation_url": "https://..." }
Een tekst die goed werkt bij de knop: "Wil je onze nieuwsbrief ontvangen? Bevestig je aanmelding met één klik."
Enkele opt-in (op aanvraag)#
Met confirmation: "none" staat iemand meteen op de lijst, zonder bevestigingsmail. Het antwoord is dan subscribed (201 voor een nieuw adres, 200 voor iemand die zich eerder had afgemeld).
Dit staat standaard uit. We zetten het alleen aan na beoordeling, voor een formulier waarvan we weten dat het adres betrouwbaar is, zoals een boeking waarvoor de klant zijn bevestiging per mail nodig heeft. Wil je het gebruiken, neem dan contact met ons op. Zonder onze goedkeuring geeft de API een foutmelding single_opt_in_not_enabled.
Ook met enkele opt-in ben je zelf verantwoordelijk voor aantoonbare toestemming. Stuur daarom altijd consented_at en consent_text mee.
Geblokkeerde adressen#
Een adres dat eerder een spamklacht gaf of niet bleek te bestaan, is geblokkeerd. Naar zo'n adres sturen wij nooit meer iets, ook geen bevestigingsmail: een adres dat niet bestaat bounct opnieuw, en iemand die klaagde kan opnieuw klagen. Met email en met none krijg je dan suppressed terug, en er verandert niets. Dat telt niet mee voor je daglimiet. De reden van de blokkade geven we niet door.
Wil de klant toch je nieuwsbrief, gebruik dan confirmation: "link" en zet de knop in je eigen mail. Een klik van de klant zelf heft de blokkade op.
Herhalen en dubbel aanmelden#
- Staat een adres al op de lijst, dan gaat er niets uit.
- Per lijst en adres sturen we hooguit 3 bevestigingsmails in 24 uur, met minstens 5 minuten ertussen. Dit geldt samen voor de API, de aanmeldpagina en het formulier op je eigen site. Een aanmelding die daarboven valt, geeft gewoon
pendingterug, zonder mail. - Stuur bij elke aanmelding een header
Idempotency-Keymee, bijvoorbeeld je eigen referentie. Komt hetzelfde verzoek met dezelfde sleutel binnen 24 uur nog eens, bijvoorbeeld door een time-out, dan krijg je hetzelfde antwoord terug en gebeurt er niets opnieuw. Alleen geslaagde antwoorden worden zo bewaard: na een foutmelding kun je het gewoon opnieuw proberen.
Status opvragen#
GET /lists/{lijst-id}/subscribers?email=...
status |
Betekenis |
|---|---|
subscribed |
Staat op de lijst. |
pending |
Er is in de afgelopen 24 uur om bevestiging gevraagd. |
unsubscribed |
Stond op de lijst en is er niet meer op. |
suppressed |
Het adres is geblokkeerd en krijgt geen mail. Alleen een klik van de klant op een bevestigingslink heft dat op. |
not_subscribed |
Onbekend op deze lijst. |
Limieten#
Per abonnement:
| Abonnement | Verzoeken per minuut per token | Aanmeldingen per dag |
|---|---|---|
| Starter | 20 | 100 |
| Plus | 30 | 250 |
| Pro | 60 | 500 |
| Max | 120 | 1.500 |
Een aanmelding telt mee voor de dag als er iets gebeurt: een bevestigingsmail, een teruggegeven link of een directe aanmelding. Een adres dat al op de lijst staat, of een aanmelding zonder mail omdat er al recent gemaild is, telt niet. De dag loopt tot middernacht UTC. Op het API-scherm zie je hoeveel je er vandaag hebt gebruikt.
Is de daglimiet bereikt, dan krijgt de eigenaar van de pagina daar één mail over. Probeer geweigerde aanmeldingen later opnieuw: na middernacht gaat het weer door.
Fouten#
Een fout heeft altijd een error met een vaste code en een message in gewone taal.
| HTTP | error |
Wanneer |
|---|---|---|
| 401 | unauthenticated |
Geen token, een onbekend token of een ingetrokken token. |
| 403 | plan_required |
Je pagina heeft op dit moment geen abonnement met de API. |
| 403 | list_not_allowed |
Het token mag deze lijst niet gebruiken. |
| 403 | single_opt_in_not_enabled |
confirmation: "none" zonder onze goedkeuring. |
| 403 | https_required |
Het verzoek kwam niet via HTTPS. |
| 404 | not_found |
De lijst bestaat niet, of hoort niet bij je pagina. |
| 422 | Een veld klopt niet. errors noemt per veld wat er mis is. |
|
| 429 | rate_limited |
Te veel verzoeken per minuut. Wacht het aantal seconden in de header Retry-After. |
| 429 | daily_limit_reached |
De daglimiet is bereikt. Retry-After geeft de seconden tot middernacht UTC. |
{ "error": "list_not_allowed", "message": "This token has no access to this list." }
{
"message": "The email field must be a valid email address.",
"errors": { "email": ["The email field must be a valid email address."] }
}
Voorbeeld#
Zet de basis-URL, het token en het lijst-id uit het API-scherm in drie variabelen:
BASE_URL="https://..." # de basis-URL van het API-scherm
TOKEN="..." # je token
LIST_ID="..." # het lijst-id
curl "$BASE_URL/lists/$LIST_ID/subscribers" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "Idempotency-Key: B-2026-0123" \
-d '{
"email": "anna@example.com",
"first_name": "Anna",
"locale": "nl",
"source": "booking-form",
"reference": "B-2026-0123",
"consented_at": "2026-11-17T10:15:00+01:00",
"consent_text": "Ja, stuur me de nieuwsbrief"
}'
En de status opvragen:
curl "$BASE_URL/lists/$LIST_ID/subscribers?email=anna@example.com" \
-H "Authorization: Bearer $TOKEN" \
-H "Accept: application/json"
Doe de aanmelding na het opslaan van de boeking of aanvraag, en laat een fout van de API de boeking niet tegenhouden. Het netst is een taak in een wachtrij die het bij een time-out of een 429 later opnieuw probeert, met dezelfde Idempotency-Key.
Bijgewerkt op 17 november 2026