Events
Define custom events and send them for a contact to start or advance automations.
An event says that something happened to one of your contacts, such as order.paid or trial.ended. Automations start on events, or wait for them.
Define an event
curl -X POST https://api.usend.et/events \
-H "Authorization: Bearer us_123456789" \
-H "Content-Type: application/json" \
-d '{ "name": "order.paid", "schema": { "total": "number", "plan": "string" } }'The optional schema maps payload keys to string, number, boolean or date (an ISO 8601 timestamp). A payload that does not match is refused. Keys outside the schema are allowed.
Names can use letters, digits, ., _, - and :. The usend: prefix is reserved for platform events. List events with GET /events, read one with GET /events/{id_or_name}, change it with PATCH /events/{id} and remove it with DELETE /events/{id}. An event that an automation uses cannot be deleted or renamed.
Send an event
curl -X POST https://api.usend.et/events/send \
-H "Authorization: Bearer us_123456789" \
-H "Idempotency-Key: order-1042-paid" \
-H "Content-Type: application/json" \
-d '{ "event": "order.paid", "email": "[email protected]", "payload": { "total": 420, "plan": "pro" } }'Use contact_id or email (not both). The contact must already exist. With an Idempotency-Key, sending the same request again returns the first occurrence and starts nothing new.
The payload is available to the automation: in conditions as event.total, and in emails as {{{TOTAL}}} (or as a template variable with the same key).
Platform events
These are sent by usend itself:
| Event | When | Payload |
|---|---|---|
usend:contact.created | A contact is created | segment_ids |
usend:contact.added_to_segment | A contact joins a segment | segment_id |
usend:topic.subscribed | A contact opts in to a topic | topic_id |
Contacts imported from a CSV file do not send platform events.