Events-API

Kontaktereignisse senden, um Segmentierung und Automations-Trigger zu steuern.

Endpunkt

Authentifizierung

Dieser Endpunkt erfordert einen API-Key mit dem Scope events:write, übergeben als Bearer-Token:

Authorization: Bearer <key>

Anfragen ohne gültigen Key liefern 401; Anfragen mit einem Key ohne den Scope events:write liefern 403. Der Endpunkt ist auf 10 Anfragen pro Sekunde begrenzt; darüber hinaus liefert er 429.

Request-Body

{
  "email": "john@example.com",
  "eventName": "purchase_completed",
  "eventProperties": {
    "orderId": "ORD-123",
    "amount": 99.99
  },
  "createContactIfNotExists": true
}

Felder:

• email (erforderlich)
• eventName (erforderlich)
• eventProperties (optionales Objekt)
• createContactIfNotExists (optionaler Boolean, Standard false)

Einschränkungen für eventName:

• muss mit einem Buchstaben beginnen
• erlaubte Zeichen: Buchstaben, Ziffern, _, -
• maximale Länge: 100

Erfolgsantwort

Liefert 201 mit dem Ergebnis des Ereignisses:

{
  "data": {
    "eventId": "evt_m6e...",
    "contactId": "j57...",
    "eventName": "purchase_completed",
    "triggeredAutomations": 1,
    "contactCreated": true
  }
}

Häufige Fehler

Fehler verwenden den Standard-Envelope { "error": { "category", "message", "data"? } }:

• 404 not_found — der Kontakt existiert nicht und createContactIfNotExists ist nicht aktiviert
• 400 invalid_input — ungültiger Ereignisname, fehlendes Pflichtfeld oder fehlerhafter JSON-Body
• 401 — fehlender oder ungültiger API-Key
• 403 — dem Key fehlt der Scope events:write
• 429 — mehr als 10 Anfragen pro Sekunde