> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.laposta.org/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.laposta.org/_mcp/server.

# Abonnenten über die API synchronisieren

> Halten Sie Ihre Liste synchron mit Ihrem Webshop oder CRM: Hinzufügen, Aktualisieren, Abmelden und Fehler abfangen.

Mit einer API-Verbindung gelangen Anmeldungen aus Ihrem Onlineshop, CRM oder von Ihrer Website automatisch in die richtige Liste.

## Felder abrufen und speichern

Eigene Felder übergeben Sie unter `custom_fields`, mit dem `custom_name` des Feldes als Schlüssel. Dieser Name weicht manchmal von dem ab, was Sie erwarten: Das Feld, das in der Anwendung „Vorname“ heißt, heißt in der API meistens `voornaam`. Rufen Sie diese Namen daher einmalig ab und hinterlegen Sie sie in Ihrem eigenen Code.

**`curl`**

```bash title="curl"
curl "https://api.laposta.nl/v2/field?list_id=BaImMu3JZA" \
  -u IHR_API_SCHLUESSEL:
```

**`PHP`**

```php title="PHP"
$laposta = new Laposta('IHR_API_SCHLUESSEL');
$velden = $laposta->fieldApi()->all('BaImMu3JZA');
```

> **Tip**
>
> Rufen Sie die Feldnamen nicht bei jeder Anmeldung ab, sondern speichern Sie sie in Ihrem eigenen System und aktualisieren Sie sie beispielsweise einmal pro Tag. Felder ändern sich selten, und jeder Aufruf zählt für Ihr Limit von 30 Anfragen pro Minute (120 bei einem bezahlten Konto). Bei einem stark frequentierten Onlineshop ist dieses Kontingent sonst schnell durch das Abrufen von Daten verbraucht, die Sie bereits hatten.

## Einen Abonnenten hinzufügen und aktualisieren

#### Übergeben Sie die E-Mail-Adresse, die IP-Adresse und Ihre eigenen Felder

Die IP-Adresse ist erforderlich: Damit halten Sie fest, woher die Anmeldung kam. Das benötigen Sie als Nachweis, dass sich jemand selbst angemeldet hat.

**`curl`**

```bash title="curl"
curl https://api.laposta.nl/v2/member \
  -u IHR_API_SCHLUESSEL: \
  -d list_id=BaImMu3JZA \
  -d ip=198.51.100.10 \
  -d email=neuer.abonnent@example.net \
  -d source_url=https://example.net/anmelden \
  -d custom_fields[voornaam]=Sanne
```

**`PHP`**

```php title="PHP"
$laposta = new Laposta('IHR_API_SCHLUESSEL');
$relatie = $laposta->memberApi()->create('BaImMu3JZA', [
    'ip' => '198.51.100.10',
    'email' => 'neuer.abonnent@example.net',
    'source_url' => 'https://example.net/anmelden',
    'custom_fields' => ['voornaam' => 'Sanne'],
]);
```

#### Fangen Sie die Nachricht ab, falls die Adresse bereits existiert

Steht die Adresse bereits in der Liste, erhalten Sie einen `400` mit dem Fehlercode `204`. Möchten Sie in diesem Fall die bestehenden Daten aktualisieren, anstatt eine Fehlermeldung zu erhalten, setzen Sie `options[upsert]` auf `true`.

#### Aktualisieren Sie Daten zu einem späteren Zeitpunkt

Führen Sie einen POST auf den Abonnenten selbst aus, um Daten zu aktualisieren. Sie müssen nur das übergeben, was sich ändert. Die anderen Felder bleiben unverändert. Sie können dabei die `member_id` verwenden, aber auch einfach die E-Mail-Adresse.

**`curl`**

```bash title="curl"
curl https://api.laposta.nl/v2/member/neuer.abonnent@example.net \
  -u IHR_API_SCHLUESSEL: \
  -d list_id=BaImMu3JZA \
  -d custom_fields[woonplaats]=Berlin
```

**`PHP`**

```php title="PHP"
$laposta->memberApi()->update('BaImMu3JZA', 'neuer.abonnent@example.net', [
    'custom_fields' => ['woonplaats' => 'Berlin'],
]);
```

## Einen Abonnenten abmelden oder löschen

Meldet sich jemand über Ihre eigene Website ab, setzen Sie den Abonnenten am besten auf abgemeldet. Das Löschen verwenden Sie nur, wenn jemand darum bittet, seine Daten vollständig zu entfernen.

| Was Sie tun | Wie                                               | Was passiert                                                                                                        |
| ----------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| Abmelden    | ändern mit `state` auf `unsubscribed`             | Der Abonnent bleibt bestehen und erhält nichts mehr. Meldet sich jemand später erneut an, sehen Sie das im Verlauf. |
| Löschen     | [Abonnent löschen](/relaties/relatie-verwijderen) | Der Abonnent wird endgültig gelöscht, einschließlich des Verlaufs.                                                  |

## Eine gesamte Liste auf einmal synchronisieren

Synchronisieren Sie pro Abonnent, dauert dies bei Tausenden Abonnenten lange und Sie stoßen an das Limit. Verwenden Sie dafür [Liste synchronisieren (Bulk)](/lijsten/lijst-synchroniseren-bulk): Hiermit senden Sie in einem einzigen Aufruf bis zu 500.000 Abonnenten als JSON.

**`JSON`**

```json title="JSON"
{
  "actions": ["add", "update"],
  "members": [
    { "email": "erster@example.net", "custom_fields": { "voornaam": "Sanne" } },
    { "email": "zweiter@example.net" }
  ]
}
```

Mit der PHP-Bibliothek senden Sie denselben Inhalt als Array:

**`PHP`**

```php title="PHP"
$laposta->listApi()->syncMembers('BaImMu3JZA', [
    'actions' => ['add', 'update'],
    'members' => [
        ['email' => 'erster@example.net', 'custom_fields' => ['voornaam' => 'Sanne']],
        ['email' => 'zweiter@example.net'],
    ],
]);
```

Mit der Aktion `unsubscribe_excluded` melden Sie jeden ab, der nicht in Ihrer Übermittlung enthalten ist. Verwenden Sie dies nur, wenn Ihr System die maßgebliche Datenquelle ist, und nicht, wenn Sie nur einen Teil Ihres Bestands übermitteln.

> **Warning**
>
> Bulk ist nicht standardmäßig aktiviert. Es ist nur für bezahlte Konten verfügbar, und Laposta muss es pro Konto freischalten. Erhalten Sie einen `401` mit „Not permitted to issue bulk requests (1)“, wenden Sie sich bitte an den Helpdesk unter [helpdesk@laposta.nl](mailto:helpdesk@laposta.nl) und geben Sie Ihre Kontonummer an.

## Worauf müssen Sie achten?

* Ein Mehrfachauswahlfeld können Sie nicht leeren, indem Sie eine leere Liste übergeben. Übergeben Sie eine leere Liste für ein `select_multiple`-Feld, werden die bestehenden Auswahlwerte nicht gelöscht. Siehe: [Häufige Fehler](/veelgemaakte-fouten-met-de-api).
* Wenn Sie ein Label als einzelnen Text übergeben, werden alle bestehenden Labels gelöscht. Senden Sie `"labels": ["Kunde"]` und nicht `"labels": "Kunde"`. Machen Sie es falsch, erhalten Sie einfach einen `200` mit `edited_count` ohne Fehlermeldung zurück, aber alle Labels sind leer. Siehe: [Häufige Fehler](/veelgemaakte-fouten-met-de-api).
* Eine unbekannte ID liefert keinen `404`, sondern einen `400` mit dem Code `203`. Prüfen Sie in Ihrem Code also darauf.
* Das Limit ist bei einem kostenlosen Konto knapper als Sie denken: 30 Anfragen pro Minute. Bauen Sie eine Wartezeit auf Basis des `Retry-After`-Headers ein, anstatt es sofort erneut zu versuchen.

## Verwandte Artikel

#### [Webhooks für Änderungen in einer Liste verwenden](/webhooks-gebruiken)

Mit einem Webhook benachrichtigt Laposta Ihr System, sobald sich jemand anmeldet…

#### [Was sind häufige Fehler bei der API?](/veelgemaakte-fouten-met-de-api)

Stolpersteine bei Verbindungen mit der Laposta API, mit dem Fehler, den Sie erhalten…

#### [Was sind die Limits und Fehlermeldungen der API?](/api-limieten-en-foutmeldingen)

Wie viele Anfragen die API pro Minute zulässt und welche Status- und Fehlercodes Sie…