Workflows

Workflows are graph-based automations that move contacts through a sequence of steps — sending emails, waiting for activity, branching on conditions, calling webhooks, updating contact data, or exiting. Each contact that enters a workflow runs through it independently as a workflow execution.

Triggers

A workflow has a single trigger that decides how contacts enter:

When you create a workflow via the API, the trigger defaults to EVENT with the event name you provide. To use MANUAL or SCHEDULE, change triggerType and triggerConfig with PATCH /workflows/:id after creation.

A workflow's trigger event name cannot be changed after the first execution — pick it carefully. Other trigger configuration (delays, conditions inside steps) remains editable.

Lifecycle and the enabled flag

Workflows are created with enabled: false. No executions start until you flip enabled to true — this is the most common reason "my workflow isn't firing."

The allowReentry flag (default false) controls whether a contact can enter the same workflow more than once. Leave it off for "first-touch only" sequences (welcome emails, onboarding) and turn it on for re-engageable journeys (re-prompts, repeated nudges).

Step types

A workflow always begins with a single auto-created TRIGGER step. You build the rest of the graph by adding steps and transitions (edges) between them.

Transitions

Transitions are the edges of the workflow graph. For most step types a transition is a simple "next" pointer. For CONDITION steps, each transition carries a branch discriminator ("yes" or "no") so the engine knows which path to take when the condition evaluates.

When deleting a step in the middle of a chain, pass ?splice=true on DELETE /workflows/:id/steps/:stepId to automatically reconnect the surrounding transitions; otherwise the deletion leaves the graph disconnected.

Executions

Each contact entering the workflow creates a WorkflowExecution. Executions move through these states:

Each execution carries a context JSON object that's merged with the contact's data when rendering templates and evaluating conditions. When you start an execution manually with POST /workflows/:id/executions, you can pass an initial context — this is how you parameterise per-execution variables (a coupon code, a referrer name) without storing them on the contact.

Locking active workflows

A workflow is locked for structural edits while it has active (RUNNING or WAITING) executions. To make breaking changes — adding/removing steps, changing the trigger event, switching trigger type — first either:

• Disable the workflow and wait for active executions to complete, or
• POST /workflows/:id/executions/cancel-all to cancel everything in flight.

Cosmetic changes (renaming, editing template content referenced by steps) don't require this.

Common patterns

• Welcome series — EVENT trigger on signed_up, send welcome email, delay 2 days, send tips email, delay 5 days, send upgrade nudge.
• Inbound auto-reply — EVENT trigger on email.received, CONDITION on event.spamVerdict == "PASS", then SEND_EMAIL with an auto-reply template. See Receiving emails.
• Re-engagement — Triggered by a segment exit (segment.active-users.exit), send a "we miss you" email, wait 7 days for any email.opened event, branch on whether the contact engaged.
• Webhook fan-out — EVENT trigger on purchase.completed, WEBHOOK step to your CRM, UPDATE_CONTACT to tag { tier: "customer" }, SEND_EMAIL with the receipt.

API reference

Workflows are managed through the /workflows API. See the API overview for the full route list — the API exposes endpoints for the workflow itself, its steps, its transitions, and its executions.

What's next