Audience
Events
Record what your users do as named events, tie them to a contact by email, and use them to trigger automations.
Events are the heartbeat of Deckle’s event-driven core. Every time something meaningful happens in your product, send an event — Deckle attaches it to the matching contact, adds it to their timeline, and lets your automations react in real time.
What are events#
An event is a named action tied to a contact by their email address. The name describes what happened, and you can attach an optional data payload with details about the action. Deckle doesn’t prescribe a taxonomy — you choose names that map to your product.
A common convention is object.action, lowercase and dot-separated:
| Event name | Fires when |
|---|---|
user.signed_up | A new user creates an account. |
order.completed | A customer finishes a purchase. |
trial.expired | A free trial reaches its end date. |
Events show up on the contact’s activity timeline alongside sends, opens, and clicks, so you get one view of everything a person has done.
Track an event#
Send an event with POST /v1/events or the SDK’s events.create. A name is required; email links the event to a contact, and data carries any structured details you want on the timeline and available to automations.
curl -X POST https://app.getdeckle.com/api/v1/events \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"name": "order.completed",
"email": "jane@example.com",
"data": {
"order_id": "ord_1234",
"total": 4200,
"currency": "usd"
}
}'Body parameters
namestringRequireduser.signed_up. Use a stable, lowercase convention so your automation triggers stay consistent.emailstringOptionalcontact_id set to null.dataobjectOptionalLinking to contacts#
Deckle matches an event to a contact by its email. When the address belongs to an existing contact, the event is attached to them and appears on their timeline immediately.
Unknown emails are never dropped. If no contact matches — or you send an event without an email at all — the event is still recorded with contact_id set to null. This means you can start emitting events before a person becomes a contact, and the history is already there once they are.
Emails are the key
Contacts are keyed by email across all of Deckle. Send events with the same address you use when you create a contact, and everything lines up on one timeline.Powering automations#
Events are what make automations event-driven. An automation can use a custom event as its trigger, so posting order.completed can start a post-purchase flow the moment it happens.
Events also wake automations that are waiting. A wait step pauses an enrollment until a specific event arrives (or a timeout elapses) — for example, wait for order.completed after a “complete your setup” nudge, and continue the moment the user follows through.
Data drives conditions
Automationcondition steps can branch on the event’s data, so a single order.completed event can route high-value orders differently from the rest.