Events

An event is a name your app emits when something happens to a person, such as trial_started or invoice_overdue. Recording one enrols that address in every active automation with an event trigger for that name. Your app makes one call and does not need to know which sequences exist, and a sequence can be added or retired without changing the app. See Automations for how this fits with the other triggers.

Events are not stored. An event that no automation is waiting for does nothing and is not an error, and an automation created later is not started by events recorded before it. The exception is an event whose name is a conversion goal: it is also recorded as a conversion and credited to the email that earned it.

Record an event

POST /v1/events · requires emails:send

Finds every automation in the workspace whose status is active, whose trigger kind is event, and whose event_name equals name exactly, including case. The address is enrolled in each of them just as Enrol someone would: each automation's automatic exits still apply, someone already active in an automation is not enrolled a second time, and an automation whose reenrollment is never does not enrol someone who has been through it before.

The response counts only the automations that actually enrolled the person. An exclusion, an existing active enrolment, or an automation that cannot enrol anyone is not reported individually; automations_started is simply lower. Check the person's enrolments on Retrieve an automation when a number is not what you expected.

The calling key's guardrails apply as they do to enrolling directly, and are checked before any automation is looked up: a key that holds its sends for approval cannot record events (403 forbidden), and a key with a recipient allowlist can record them only for addresses on it (403 recipient_not_allowed). A key's daily limit is not checked, and the steps the automations send do not count against it.

Body

Example

curl -X POST https://api.sendraven.ai/v1/events \
  -H "Authorization: Bearer $SENDRAVEN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "name": "trial_started", "email": "ana@example.com", "variables": { "name": "Ana" } }'

Response

200 OK

{ "event": "trial_started", "automations_started": 2, "conversion_id": null }

conversion_id is the conversion this event recorded when name is a conversion goal, and null otherwise. It starts pending and is credited a few seconds later; read it with Retrieve a conversion.

Errors