Sign in
latestOpenAPI 3.1.0raw.githubusercontent.com2026-08-17263153961.8 KB

9da9d1816e27

Subscribers

Trigger event for subscriber

Triggers an event for a subscriber. Creates the subscriber if they don't exist and applies the workspace default lists setting. Creates the event definition if it doesn't exist. When the workspace has double opt-in enabled, a brand-new subscriber is created pending confirmation, the confirmation email is queued, and matching sequences wait at their trigger until the subscriber confirms.

post/subscribers/events

Request body

emailstring email

Required when creating a new subscriber. Optional when externalId identifies an existing subscriber.

externalIdstring

Customer-owned app/customer/user ID

firstNamestring

First name to set if creating the subscriber.

lastNamestring

Last name to set if creating the subscriber.

eventstring required
propertiesobject

Event properties/metadata

customAttributesobject

Optional attributes to set on the subscriber if created

occurredAtstring date-time

When the event actually happened. Defaults to now. More than an hour in the past records it as history - stored with the real timestamp and counted by segments, but running no sequences, sync rules, waiting steps, goal conversions or webhooks, and the response carries historical=true. Older than the 5-year event retention window is rejected with 400.

eventIdstring

Caller-owned event ID used as an idempotency key on both paths. A repeated live event returns the existing event with duplicate=true. A repeated historical event remains a historical response and increments duplicates instead. Best-effort for live events sent within about a second of each other, so a producer needing a strict guarantee should keep its own ledger.

Example request

{
  "email": "user@example.com",
  "externalId": "user_123",
  "firstName": "John",
  "lastName": "Doe",
  "event": "purchase.completed",
  "properties": {
    "amount": 9900,
    "currency": "USD",
    "productId": "prod_123"
  },
  "occurredAt": "2024-11-02T10:00:00Z",
  "eventId": "inv_9182"
}

Response

Event triggered successfully

successboolean
duplicateboolean

Present and true when a live event's supplied eventId was already recorded for this contact and event name. Nothing was written and no side effects ran; event holds the existing event. Historical responses use duplicates instead.

historicalboolean

Present and true when occurredAt selected the historical import path.

insertedinteger

Historical event rows inserted by this request.

duplicatesinteger

Historical event rows skipped because their idempotency receipt already existed.

sideEffectFailuresstring[]

Present when the event was recorded but one or more side-effect stages (e.g. apply-sync-rules, trigger-event-automations) failed. Retry-sensitive callers should treat these as partial failures.

Example response

{
  "success": true,
  "duplicate": true,
  "historical": true,
  "inserted": 1,
  "sideEffectFailures": [
    "apply-sync-rules"
  ]
}