Workflows
A workflow says what happens after a customer does something: wait, check, send an email, stop. Your AI assistant usually writes it for you with workflows_upsert; this page is what it writes.
A definition
Section titled “A definition”A workflow has an id (lowercase letters, digits, _ and -, up to 64 characters), a name, and a definition: one trigger and 1 to 50 steps, run in order.
{ "trigger": { "type": "event", "event": "user.signed_up" }, "steps": [ { "id": "wait-3-days", "type": "delay", "seconds": 259200 }, { "id": "no-project-yet", "type": "condition", "attribute": "hasProject", "operator": "not_equals", "value": true }, { "id": "nudge", "type": "send_email", "from": "hello@yourdomain.example", "subject": "Need a hand creating your first project?", "body": "Most people get started in two minutes. Reply if anything is in the way." } ]}Trigger
Section titled “Trigger”{ "type": "event", "event": "<name>" } starts a run for a customer each time events.track records an event with that name for them (Customers and events).
A customer has at most one active run of a workflow at a time: an event that arrives while the customer’s earlier run is still going starts no second run.
Time-based triggers (a date attribute, a schedule, a one-off time) are planned.
Each step has an id, unique in the workflow, in the same format as the workflow’s. Run state and the step log refer to it.
| Type | Fields | What it does |
|---|---|---|
delay |
seconds: a whole number from 1 to 31,536,000 (365 days) |
Waits, then continues. |
condition |
attribute, operator, and value |
Reads the customer’s attribute when the step runs. If the condition holds, the run continues; if not, it ends with condition_not_met. operator is equals or not_equals (with a value: a string, number, or boolean) or exists or not_exists (without one). |
send_email |
from, subject (up to 998 characters), body (up to 100,000 characters) |
Sends one plain-text email to the customer’s address, after the checks in Sending. |
exit |
none | Ends the run. |
A run that reaches the end of its steps is complete.
Not built yet, and planned: HTML bodies and templates with variables, branching conditions, outbound webhook steps, a goal that ends the run once met, and test runs that skip delays.
Versions
Section titled “Versions”Every save of a changed definition is a new, numbered version. Saving the same definition again changes nothing.
- Saving never changes what runs.
latestVersionis the last version saved;liveVersionis the one new runs start on. A new workflow is adraftwith no live version. - Activating makes the latest version live.
workflows.activatepublishes the latest version; a draft becomesactive. For a version that sends email, activation needs a confirmation and a human approval first (Sending). - A save can require the version it was based on. With
expectedLatestVersion(0 for a new workflow), a save that would change the workflow (a new version or a new name) is refused withconflictif another save came first, and the error’slatestVersionsays which version to read; a save that changes nothing is never refused. - Started runs keep their version. A run is pinned to the version it started on, so publishing a new version never changes an email that a run already waiting would send.
Reading what happened
Section titled “Reading what happened”messages.list lists a customer’s messages, and messages.get returns one with its runLog: one line per step of its run with the outcome, such as started, a skip and its reason, or the run’s end. That log is how you, or your assistant, answer “why did this customer not get the email?”. A run that ends or waits before its send step has no message, and an API to read such runs is planned; Troubleshooting lists what to check.