Synchronising subscribers through the API

With an API connection, sign-ups from your webshop, CRM or website automatically end up in the right list.

Retrieving and storing fields

You pass custom fields under custom_fields, using the field’s custom_name as the key. This name sometimes differs from what you might expect: the field called ‘First name’ in the application is usually called voornaam in the API. Therefore, retrieve these names once and store them in your own code.

curl "https://api.laposta.nl/v2/field?list_id=BaImMu3JZA" \
  -u YOUR_API_KEY:

Adding and updating a subscriber

curl https://api.laposta.nl/v2/member \
  -u YOUR_API_KEY: \
  -d list_id=BaImMu3JZA \
  -d ip=198.51.100.10 \
  -d email=new.subscriber@example.net \
  -d source_url=https://example.net/subscribe \
  -d custom_fields[voornaam]=Sanne

$laposta = new Laposta('YOUR_API_KEY');
$subscriber = $laposta->memberApi()->create('BaImMu3JZA', [
    'ip' => '198.51.100.10',
    'email' => 'new.subscriber@example.net',
    'source_url' => 'https://example.net/subscribe',
    'custom_fields' => ['voornaam' => 'Sanne'],
]);

curl https://api.laposta.nl/v2/member/new.subscriber@example.net \
  -u YOUR_API_KEY: \
  -d list_id=BaImMu3JZA \
  -d custom_fields[woonplaats]=Utrecht

$laposta->memberApi()->update('BaImMu3JZA', 'new.subscriber@example.net', [
    'custom_fields' => ['woonplaats' => 'Utrecht'],
]);

Unsubscribing or deleting a subscriber

If someone unsubscribes via your own site, it is best to set the subscriber to unsubscribed. Only use delete if someone asks to have their data completely erased.

Synchronising an entire list at once

If you synchronise per subscriber, it will take a long time when you have thousands of subscribers and you will hit the rate limit. Instead, use Synchronise list (bulk): this allows you to send up to 500,000 subscribers as JSON in a single call.

{
  "actions": ["add", "update"],
  "members": [
    { "email": "first@example.net", "custom_fields": { "voornaam": "Sanne" } },
    { "email": "second@example.net" }
  ]
}

With the PHP library, you send the same content as an array:

$laposta->listApi()->syncMembers('BaImMu3JZA', [
    'actions' => ['add', 'update'],
    'members' => [
        ['email' => 'first@example.net', 'custom_fields' => ['voornaam' => 'Sanne']],
        ['email' => 'second@example.net'],
    ],
]);

With the unsubscribe_excluded action, you unsubscribe everyone who is not included in your submission. Only use this if your system is the source of truth, and not if you are only submitting a part of your file.

What should you watch out for?

• You cannot empty a multiple-choice field by sending an empty list. If you send an empty list for a select_multiple field, the existing choices are not cleared. See: Common mistakes.
• If you send a label as plain text, all existing labels are cleared. Send "labels": ["Customer"] and not "labels": "Customer". If you do it wrong, you will simply receive a 200 with edited_count without an error message, but all labels will be empty. See: Common mistakes.
• An unknown ID does not return a 404, but a 400 with code 203. Make sure to test for that.
• The limit is tighter than you might think on a free account: 30 requests per minute. Build in a delay based on the Retry-After header instead of retrying immediately.

Related articles