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
- Öffnen Sie Einstellungen → API & MCP. Dafür brauchen Sie die Rolle Admin.
- Vergeben Sie unter Neuer API-Key einen Namen, etwa „Shop-Integration“.
- Wählen Sie die Berechtigungen: Alle (inkl. Versand), Nur lesen oder einzelne Scopes wie
contacts:writeodertransactional:send. - 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" } }confirmationToken, erst der zweite Aufruf mit diesem Token sendet. Das Token ist an die exakte Eingabe gebunden und 10 Minuten gültig.