Sign-up API
Sign subscribers up from your own website or system, for example with a checkbox on a booking.
With the API your own website signs people up for a list, from your server. Think of a booking or quote form with a checkbox "Keep me posted". When the box is ticked, your site passes the email address to ListMailing, and we take care of the confirmation, the unsubscribe link and the rest.
The API comes with a paid plan. This topic is written for the developer who builds the connection.
Creating a token#
- Open API in the menu under Newsletter.
- Press Create token, give the token a name (for example "booking form") and choose the lists it may sign people up for.
- Copy the token straight away. You only see it once: we only keep an encrypted version.
The same window shows the base URL and the list id of every list you chose. That is all your site needs.
A token can only sign people up for the lists you choose for it. Use a token of its own for every website or system, so you can revoke one without touching the others. You revoke a token with Revoke in the table of tokens. A website using a revoked token gets an error from then on.
Keep the token on your server only. Never put it in JavaScript or HTML a visitor can see.
Requests#
- HTTPS only.
- Send the token as
Authorization: Bearer <token>. - Send
Content-Type: application/jsonandAccept: application/json. - Responses are always JSON.
Signing someone up#
POST /lists/{list-id}/subscribers, after the base URL.
| Field | Type | Required | Notes |
|---|---|---|---|
email |
text | yes | The email address, at most 255 characters. Case does not matter. |
first_name |
text | no | First name, at most 255 characters. Never overwrites a name we already have. |
last_name |
text | no | Last name, at most 255 characters. |
locale |
nl or en |
no | Language of the confirmation mail. Without it, the language of your page. |
source |
text | no | A short origin, for example booking-form. At most 64 characters. |
reference |
text | no | Your own reference, for example the booking number. At most 100 characters. |
consented_at |
date and time | no | When the box was ticked, in ISO 8601, such as 2026-11-17T10:15:00+01:00. |
consent_text |
text | no | The sentence next to the box. At most 1000 characters. |
confirmation |
email, link or none |
no | How the sign-up is confirmed, see below. Defaults to email. |
Send source, reference, consented_at and consent_text when you have them. They let you show later when and how someone gave consent. You see them with the contact and in the export.
The response always has a status and a subscriber_id:
| HTTP | status |
Meaning |
|---|---|---|
| 201 | pending |
New address. A confirmation mail has been sent. |
| 200 | pending |
A confirmation was asked for before. A new mail only goes out when that is allowed (see below). |
| 200 | already_subscribed |
Already on the list. Nothing is sent. |
| 200 | resubscribe_pending |
Unsubscribed before and signs up again. A confirmation mail has been sent. |
| 200 | suppressed |
The address is blocked. Nothing is sent and nothing changes. See Blocked addresses. |
{ "status": "pending", "subscriber_id": null }
subscriber_id is our id of the contact. It is null as long as the address is not confirmed, because we do not store the address until the confirmation link is clicked.
Confirmation#
By default the person gets a confirmation mail from your sender, with a link. That link opens a page with a Confirm sign-up button, and only after pressing it are they on the list. Opening the link alone is not enough, because many business mail servers open every link in a mail to scan it for viruses, before the recipient even sees the mail. That way you know the address is right and that its owner wanted this. The confirmation field gives you two other options.
confirmation: "link": the button in your own mail. We send nothing, but you get the confirmation link back in confirmation_url. Put it as a button in a mail you send anyway, such as a booking confirmation. Your customer then gets one mail instead of two, and it is still a real double opt-in: the link opens the same page with the confirm button. The link is valid for 30 days.
{ "status": "pending", "subscriber_id": null, "confirmation_url": "https://..." }
A text that works well next to the button: "Would you like our newsletter? Confirm your sign-up with one click."
Single opt-in (on request)#
With confirmation: "none" someone is on the list straight away, without a confirmation mail. The response is then subscribed (201 for a new address, 200 for someone who had unsubscribed before).
This is off by default. We only turn it on after a review, for a form where we know the address is reliable, such as a booking for which the customer needs their confirmation by mail. If you want to use it, get in touch with us. Without our approval the API answers with the error single_opt_in_not_enabled.
With single opt-in you are still responsible for being able to show consent. So always send consented_at and consent_text.
Blocked addresses#
An address that made a spam complaint before or turned out not to exist is blocked. We never send anything to such an address again, not even a confirmation mail: an address that does not exist bounces again, and someone who complained may complain again. With email and with none you get suppressed back, and nothing changes. It does not count towards your daily limit. We do not pass on the reason for the block.
If the customer does want your newsletter, use confirmation: "link" and put the button in your own mail. A click by the customer themselves lifts the block.
Repeats and double sign-ups#
- When an address is already on the list, nothing is sent.
- Per list and address we send at most 3 confirmation mails in 24 hours, at least 5 minutes apart. This counts the API, the signup page and the form on your own site together. A sign-up beyond that simply returns
pending, without a mail. - Send an
Idempotency-Keyheader with every sign-up, for example your own reference. When the same request comes in again with the same key within 24 hours, for instance after a timeout, you get the same response back and nothing happens again. Only successful responses are kept this way: after an error you can simply try again.
Looking up a status#
GET /lists/{list-id}/subscribers?email=...
status |
Meaning |
|---|---|
subscribed |
On the list. |
pending |
A confirmation was asked for in the last 24 hours. |
unsubscribed |
Was on the list and is not any more. |
suppressed |
The address is blocked and gets no mail. Only a click by the customer on a confirmation link lifts that. |
not_subscribed |
Unknown on this list. |
Limits#
Per plan:
| Plan | Requests per minute per token | Sign-ups per day |
|---|---|---|
| Starter | 20 | 100 |
| Plus | 30 | 250 |
| Pro | 60 | 500 |
| Max | 120 | 1,500 |
A sign-up counts towards the day when something happens: a confirmation mail, a link handed back or a direct sign-up. An address already on the list, or a sign-up without a mail because one was sent recently, does not count. The day runs until midnight UTC. The API screen shows how many you used today.
When the daily limit is reached, the owner of the page gets one mail about it. Try refused sign-ups again later: after midnight they go through again.
Errors#
An error always has an error with a fixed code and a message in plain language.
| HTTP | error |
When |
|---|---|---|
| 401 | unauthenticated |
No token, an unknown token or a revoked token. |
| 403 | plan_required |
Your page has no plan with the API at the moment. |
| 403 | list_not_allowed |
The token may not use this list. |
| 403 | single_opt_in_not_enabled |
confirmation: "none" without our approval. |
| 403 | https_required |
The request did not come in over HTTPS. |
| 404 | not_found |
The list does not exist, or does not belong to your page. |
| 422 | A field is wrong. errors names what is wrong per field. |
|
| 429 | rate_limited |
Too many requests per minute. Wait the number of seconds in the Retry-After header. |
| 429 | daily_limit_reached |
The daily limit is reached. Retry-After gives the seconds until midnight 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."] }
}
Example#
Put the base URL, the token and the list id from the API screen in three variables:
BASE_URL="https://..." # the base URL from the API screen
TOKEN="..." # your token
LIST_ID="..." # the list 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": "en",
"source": "booking-form",
"reference": "B-2026-0123",
"consented_at": "2026-11-17T10:15:00+01:00",
"consent_text": "Yes, send me the newsletter"
}'
And looking up the status:
curl "$BASE_URL/lists/$LIST_ID/subscribers?email=anna@example.com" \
-H "Authorization: Bearer $TOKEN" \
-H "Accept: application/json"
Sign people up after the booking or request is saved, and never let an error from the API stop the booking. The cleanest way is a queued job that tries again later after a timeout or a 429, with the same Idempotency-Key.
Updated on 17 November 2026