Workflows

Automate email sequences with workflows. Create a workflow, add steps (send emails, wait, branch on conditions), then activate it. Steps are managed individually via the API, and workflows can be triggered automatically by events or manually for specific contacts.

POST

/workflows

Create a new workflow. Workflows start in 'draft' status. Add steps after creation, then activate.

json

{
  "name": "Welcome Sequence",
  "trigger_type": "contact.created",
  "trigger_config": {}
}

GET

/workflows

List all workflows with their status and trigger type.

json

{
  "data": [
    {
      "id": "wf_abc123def456ghi789",
      "name": "Welcome Sequence",
      "trigger_type": "contact.created",
      "status": "active",
      "created_at": "2026-03-23T10:00:00.000Z"
    },
    {
      "id": "wf_jkl012mno345pqr678",
      "name": "Re-engagement",
      "trigger_type": "manual",
      "status": "paused",
      "created_at": "2026-03-20T10:00:00.000Z"
    }
  ]
}

GET

/workflows/:id

Retrieve a single workflow with all steps and configuration.

json

{
  "workflow": {
    "id": "wf_abc123def456ghi789",
    "name": "Welcome Sequence",
    "trigger_type": "contact.created",
    "trigger_config": {},
    "status": "active",
    "steps": [
      {
        "id": 1,
        "step_type": "send_email",
        "position": 0,
        "config": { "template_id": "tpl_welcome_123" },
        "created_at": "2026-03-23T10:01:00.000Z"
      },
      {
        "id": 2,
        "step_type": "wait",
        "position": 1,
        "config": { "delay": "3d" },
        "created_at": "2026-03-23T10:02:00.000Z"
      },
      {
        "id": 3,
        "step_type": "send_email",
        "position": 2,
        "config": { "template_id": "tpl_tips_456" },
        "created_at": "2026-03-23T10:03:00.000Z"
      }
    ],
    "created_at": "2026-03-23T10:00:00.000Z",
    "updated_at": "2026-03-23T10:03:00.000Z"
  }
}

POST

/workflows/:id/steps

Add a step to a workflow. Steps are ordered by position (0-based). The workflow must be in 'draft' or 'paused' status.

json

{
  "step_type": "send_email",
  "config": {
    "template_id": "tpl_welcome_123"
  },
  "position": 0
}

PATCH

/workflows/:id/steps/:stepId

Update a workflow step's configuration.

json

{
  "config": {
    "template_id": "tpl_welcome_v2"
  }
}

DELETE

/workflows/:id/steps/:stepId

Remove a step from a workflow.

json

{
  "success": true
}

POST

/workflows/:id/activate

Activate a workflow. New contacts matching the trigger will begin the sequence.

json

{
  "workflow": {
    "id": "wf_abc123def456ghi789",
    "status": "active"
  }
}

POST

/workflows/:id/pause

Pause an active workflow. Contacts already in the workflow will stop receiving further steps.

json

{
  "workflow": {
    "id": "wf_abc123def456ghi789",
    "status": "paused"
  }
}

POST

/workflows/:id/trigger

Manually trigger a workflow for a specific contact. Only works for workflows with 'manual' trigger type that are in 'active' status.

json

{
  "contact_id": 1
}

DELETE

/workflows/:id

Delete a workflow. Any contacts currently enrolled will be removed from the sequence.

json

{
  "deleted": true
}

Step Types

Workflows support three step types that can be combined to create complex sequences:

send_email

Send an email using a published template. Template variables are populated from the contact's data and properties.

json

{
  "step_type": "send_email",
  "config": {
    "template_id": "tpl_abc123",
    "from": "you@yourdomain.com"
  },
  "position": 0
}

wait

Pause the sequence for a specified duration before continuing to the next step. Supports minutes (m), hours (h), and days (d).

json

{
  "step_type": "wait",
  "config": {
    "delay": "3d"
  },
  "position": 1
}

// Other examples: "30m", "12h", "7d"

condition

Branch the workflow based on a contact property. Define separate step sequences for the true and false paths.

json

{
  "step_type": "condition",
  "config": {
    "field": "plan",
    "operator": "equals",
    "value": "pro",
    "on_true": [{ "type": "send_email", "template_id": "tpl_pro" }],
    "on_false": [{ "type": "send_email", "template_id": "tpl_free" }]
  },
  "position": 2
}

Triggers

Workflows are started by a trigger event. Set the trigger_type when creating a workflow:

Trigger	Description
`contact.created`	Automatically enrolls new contacts when they are created
`contact.subscribed`	Enrolls contacts when they subscribe to a topic
`manual`	Only enrolls contacts when explicitly triggered via the POST /workflows/:id/trigger endpoint

Building a Workflow

Here's a complete example of creating a welcome sequence:

typescript

// 1. Create the workflow
const { workflow } = await poststack.workflows.create({
  name: 'Welcome Sequence',
  trigger_type: 'contact.created',
});

// 2. Add steps in order
await poststack.workflows.addStep(workflow.id, {
  step_type: 'send_email',
  config: { template_id: 'tpl_welcome' },
  position: 0,
});

await poststack.workflows.addStep(workflow.id, {
  step_type: 'wait',
  config: { delay: '3d' },
  position: 1,
});

await poststack.workflows.addStep(workflow.id, {
  step_type: 'send_email',
  config: { template_id: 'tpl_getting_started' },
  position: 2,
});

// 3. Activate the workflow
await poststack.workflows.activate(workflow.id);