Events API

Send contact events to drive segmentation and automation triggers.

Endpoint

Authentication

This endpoint requires an API key with the events:write scope, passed as a bearer token:

Authorization: Bearer <key>

Requests without a valid key return 401; requests with a key that lacks the events:write scope return 403. The endpoint is rate limited to 10 requests per second, beyond which it returns 429.

Request body

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

Fields:

• email (required)
• eventName (required)
• eventProperties (optional object)
• createContactIfNotExists (optional boolean, default false)

eventName constraints:

• must start with a letter
• allowed chars: letters, numbers, _, -
• max length: 100

Success response

Returns 201 with the event result:

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

Common errors

Errors use the standard envelope { "error": { "category", "message", "data"? } }:

• 404 not_found — contact does not exist and createContactIfNotExists is not enabled
• 400 invalid_input — invalid event name, missing required field, or malformed JSON body
• 401 — missing or invalid API key
• 403 — key lacks the events:write scope
• 429 — more than 10 requests per second