Abonnenten über die API synchronisieren

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 "https://api.laposta.nl/v2/field?list_id=BaImMu3JZA" \
  -u IHR_API_SCHLUESSEL:

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

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

$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

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

$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	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): Hiermit senden Sie in einem einzigen Aufruf bis zu 500.000 Abonnenten als JSON.

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

$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.

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 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.
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.
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.