Skip to main content
Workflows are automated email sequences that run in response to events you send from your application. When a contact triggers the workflow’s entry event, Plunk starts an execution and moves the contact through the configured steps — sending emails, waiting, evaluating conditions, calling webhooks, and updating contact data.

​
Prerequisites

Before creating a workflow, you need:

Events via /v1/track

Workflows are triggered by events. Send events from your application using POST /v1/track to create or update contacts and fire the trigger.

Email templates

Send Email steps require a saved template. Create your templates before building the workflow.

​
Creating a workflow

1

Open Workflows in the dashboard

Navigate to Workflows and click Create Workflow.
2

Set the trigger event

Enter the event name that starts this workflow (e.g., user.signup, purchase.completed). The trigger event cannot be changed after the workflow is created — choose it carefully.
The trigger event name is permanent. If you need a different trigger, you must create a new workflow.
3

Configure workflow options

  • Name — internal label for the workflow
  • Description — optional notes
  • Allow re-entry — if enabled, a contact can enter the workflow again after completing or exiting a previous run
4

Add steps

Use the visual editor to add steps to the workflow. Connect steps with transitions to define the execution path. See Step types below.
5

Enable the workflow

Toggle the workflow to Enabled when you are ready to accept incoming executions. Disabled workflows do not start new executions even when the trigger event is received.

​
Step types

Each step in a workflow performs a specific action. Steps are connected by transitions, which can be conditional (for branching) or unconditional.
Step typeDescription
Send EmailSends an email to the contact using a specified template. Contact data and execution context are available as template variables.
DelayPauses the execution for a fixed duration (e.g., 2 hours, 3 days) before proceeding.
Wait for EventPauses the execution until the contact triggers a specific event. You can set a timeout — if the event is not received within the timeout window, the execution proceeds down the timeout branch.
ConditionEvaluates a condition against contact data or event data and routes the execution to a yes or no branch.
WebhookMakes an HTTP POST request to an external URL with the contact and event data as the payload.
Update ContactUpdates one or more fields on the contact’s data record mid-execution.
ExitTerminates the execution immediately, optionally with a reason.

​
Send Email step

Attach a template to the step. The contact’s data, reserved variables ({{email}}, {{unsubscribeUrl}}, etc.), and the execution context are all available for variable substitution in the template.
The template type determines delivery behavior. A marketing template will not be sent to an unsubscribed contact. A transactional template is always delivered. See Template types.

​
Delay step

Configure a delay with an amount and unit: 
{
  "amount": 24,
  "unit": "hours"
}
The execution is paused and scheduled to resume after the specified duration. The worker processes the scheduled resume automatically.

​
Wait for Event step

The execution pauses until the contact fires a specific event. Configure the event name and an optional timeout: 
{
  "eventName": "email.clicked",
  "timeout": 86400
}
  • If the event arrives before the timeout, the execution follows the event-received branch.
  • If the timeout elapses first, the execution follows the timeout branch.

​
Condition step

Evaluate a field on the contact or event data using comparison operators: 
{
  "field": "contact.data.plan",
  "operator": "equals",
  "value": "pro"
}
The step routes executions to a yes branch (condition met) or no branch (condition not met). Use conditions to branch the workflow based on contact properties or engagement behavior.

​
Webhook step

Sends a POST request to a URL you control. The request body contains the contact and event data at the time of execution. Use this to integrate with external systems or trigger side effects in your application. For the full webhook payload format, see the Webhooks guide.

​
Update Contact step

Modify fields on the contact record from within the workflow. Specify key-value pairs to set: 
{
  "data": {
    "onboarded": true,
    "plan": "pro"
  }
}
Updates take effect immediately and are visible to subsequent steps in the same execution.

​
Exit step

Terminates the execution early. Useful for short-circuiting the workflow when a condition means the remaining steps are unnecessary (e.g., the contact has already converted).

​
Managing executions

The Executions tab on a workflow’s detail page shows all active and completed executions with their current status.

​
Execution statuses

StatusDescription
RUNNINGActively executing through steps
WAITINGPaused at a Delay or Wait for Event step
COMPLETEDFinished all steps normally
EXITEDTerminated by an Exit step
FAILEDStopped due to an error
CANCELLEDManually canceled

​
Canceling executions

You can cancel a single execution or all active executions for a workflow: 
curl -X DELETE https://api.useplunk.com/workflows/{workflowId}/executions/{executionId} \
  -H "Authorization: Bearer sk_live_..."

​
Workflow locking

A workflow is locked while it has active executions. You cannot edit the workflow’s steps or transitions while executions are running or waiting. To make changes:
  1. Disable the workflow to stop new executions from starting.
  2. Either wait for active executions to complete naturally, or cancel all executions to clear them immediately.
  3. Make your edits, then re-enable the workflow.
Canceling all executions is irreversible. Contacts whose executions are canceled will not receive any remaining steps in that run. If re-entry is disabled, they will not enter the workflow again even if the trigger event fires.

​
API reference

See the full endpoint reference at Workflows.

Build docs developers (and LLMs) love

Get started for freeTalk to us