Zum Inhalt springen

REST-API und API-Keys

API-Keys mit Berechtigungen anlegen, per Bearer-Token authentifizieren und alle Endpunkte in der OpenAPI-Spezifikation finden.

Alles, was Sie in der App tun, geht auch per REST-API: Kontakte anlegen, Kampagnen erstellen, Statistiken abrufen und mehr.

Basis-URL und Spezifikation

  • Basis-URL: https://app.example.com/api/v1
  • OpenAPI-Spezifikation: https://app.example.com/api/v1/openapi.json. Sie listet jeden Endpunkt mit Beispiel und benötigter Berechtigung.

API-Key anlegen

  1. Öffnen Sie Einstellungen → API & MCP. Dafür brauchen Sie die Rolle Admin.
  2. Vergeben Sie unter Neuer API-Key einen Namen, etwa „Shop-Integration“.
  3. Wählen Sie die Berechtigungen: Alle (inkl. Versand), Nur lesen oder einzelne Scopes wie contacts:write oder transactional:send.
  4. Klicken Sie auf Key erstellen und kopieren Sie den Key. Er beginnt mit nl_ und wird nur einmal angezeigt.

In der Liste sehen Sie den Anfang jedes Keys, seine Berechtigungen und wann er zuletzt genutzt wurde. Mit Widerrufen sperren Sie ihn sofort. Ein Key gilt nur, solange die Person, die ihn erstellt hat, Mitglied im Workspace ist.

Authentifizierung

Senden Sie den Key bei jedem Aufruf im Header Authorization:

curl https://app.example.com/api/v1/campaigns \
  -H "Authorization: Bearer nl_…"

Ein Kontakt wird per E-Mail-Adresse angelegt oder aktualisiert:

curl -X POST https://app.example.com/api/v1/contacts \
  -H "Authorization: Bearer nl_…" \
  -H "Content-Type: application/json" \
  -d '{"email":"max@example.com","firstName":"Max","tags":["kunde"],"attributes":{"city":"Berlin"}}'

Fehler

Fehler kommen immer im selben Format mit passendem HTTP-Status, zum Beispiel 401 ohne gültigen Key, 403 bei fehlender Berechtigung oder 404, wenn etwas nicht existiert. Ungültige Eingaben liefern 400 mit dem Code validation_error und einer Liste der Probleme.

{ "error": { "code": "not_found", "message": "Kampagne nicht gefunden" } }
Versand und Antworten laufen per API immer zweistufig: Der erste Aufruf liefert eine Vorschau und ein confirmationToken, erst der zweite Aufruf mit diesem Token sendet. Das Token ist an die exakte Eingabe gebunden und 10 Minuten gültig.
Weiter: Transaktionsmails per API