101 lines
8.0 KiB
Plaintext
101 lines
8.0 KiB
Plaintext
---
|
|
title: Workflows
|
|
description: Build automated, multi-step contact journeys triggered by events, segments, schedules, or manual entry
|
|
icon: Workflow
|
|
---
|
|
|
|
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:
|
|
|
|
| Trigger type | When it fires |
|
|
| ------------ | ------------------------------------------------------------------------------------------------------ |
|
|
| `EVENT` | Any time a matching event is tracked on a contact (custom event via `/v1/track`, system events such as `email.received` or `contact.subscribed`, or segment entry/exit events). |
|
|
| `MANUAL` | Only when you explicitly start an execution via `POST /workflows/:id/executions`. |
|
|
| `SCHEDULE` | On a recurring schedule defined by `triggerConfig` (e.g. cron expression). |
|
|
|
|
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.
|
|
|
|
| Step type | Purpose | Required config |
|
|
| ----------------- | ------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------- |
|
|
| `TRIGGER` | Auto-created entry point. Holds the trigger configuration. | `eventName` (for `EVENT` trigger) |
|
|
| `SEND_EMAIL` | Sends an email to the contact using a template. Template variables resolve from contact data + execution context. | `templateId`, optional `from` override |
|
|
| `DELAY` | Pauses the execution for a fixed duration before continuing. | `amount`, `unit` (`minutes` / `hours` / `days`) |
|
|
| `WAIT_FOR_EVENT` | Pauses until a specified event is tracked on the contact, with a timeout fallback. | `eventName`, `timeout` (seconds) |
|
|
| `CONDITION` | Branches the execution based on contact data or event data. Each `CONDITION` step has two outgoing transitions tagged `yes` / `no`. | A filter expression (same shape as segment filters) |
|
|
| `WEBHOOK` | Calls an external HTTPS endpoint with contact + execution context as the JSON body. `url`, header values, and `body` support `{{variables}}`. | `url`, optional `method`, `headers`, `body` |
|
|
| `UPDATE_CONTACT` | Patches contact data — useful for tagging contacts as they progress (`{ stage: "activated" }`). | `data` object |
|
|
| `EXIT` | Terminates the execution. Optionally records an `exitReason` for analytics. | optional `reason` |
|
|
|
|
## 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:
|
|
|
|
| Status | Meaning |
|
|
| ----------- | --------------------------------------------------------------------------------------------- |
|
|
| `RUNNING` | Currently processing a step (or about to). |
|
|
| `WAITING` | Paused inside a `DELAY` or `WAIT_FOR_EVENT` step. |
|
|
| `COMPLETED` | Reached the end of the graph successfully. |
|
|
| `EXITED` | Hit an `EXIT` step. `exitReason` records why. |
|
|
| `FAILED` | An unrecoverable error occurred (e.g. webhook returned non-2xx after retries, template not found). |
|
|
| `CANCELLED` | Cancelled manually via the API or dashboard. |
|
|
|
|
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](/guides/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](/api-reference/overview#workflows) for the full route list — the API exposes endpoints for the workflow itself, its steps, its transitions, and its executions.
|
|
|
|
## What's next
|
|
|
|
<Cards>
|
|
<Card title="Templates" href="/concepts/templates">
|
|
Author the email content used by `SEND_EMAIL` steps.
|
|
</Card>
|
|
<Card title="Receiving emails" href="/guides/receiving-emails">
|
|
Trigger workflows from inbound mail with `email.received`.
|
|
</Card>
|
|
<Card title="Webhooks" href="/guides/webhooks">
|
|
Use `WEBHOOK` steps to call your own services from a workflow.
|
|
</Card>
|
|
<Card title="Segments" href="/concepts/segments">
|
|
Trigger workflows from segment entry / exit events.
|
|
</Card>
|
|
</Cards>
|