Skip to content

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 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."
}
]
}

{ "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.

Every save of a changed definition is a new, numbered version. Saving the same definition again changes nothing.

  • Saving never changes what runs. latestVersion is the last version saved; liveVersion is the one new runs start on. A new workflow is a draft with no live version.
  • Activating makes the latest version live. workflows.activate publishes the latest version; a draft becomes active. 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 with conflict if another save came first, and the error’s latestVersion says 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.

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.