Workflows

Workflows are multi-step notification pipelines that orchestrate delivery across email, push, SMS, and in-app channels. You can create and manage workflows through the Dashboard or the API.

Overview

Instead of sending to a single channel, define a workflow that delivers through multiple channels with conditions and delays:

// Trigger a workflow
await zyphr.workflows.trigger('order-confirmation', {
  to: 'user_123',
  payload: {
    orderId: 'ORD-456',
    orderTotal: '$49.99',
  },
});

A workflow might:

1. Send an in-app notification immediately
2. Wait 1 hour
3. If the in-app notification wasn't read, send a push notification
4. Wait 24 hours
5. If push wasn't delivered, send an email

Key Concepts

Workflow

A reusable blueprint defining the notification delivery pipeline. Workflows have a unique key, status (draft/active/paused/archived), and contain ordered steps.

Steps

Steps are the building blocks of a workflow:

Step Type	Description
Email	Send an email notification
Push	Send a push notification
SMS	Send an SMS message
In-App	Send an in-app notification
Delay	Pause execution for a duration
Branch	Conditional logic based on previous step outcomes

Executions

When a workflow is triggered, an execution is created for each subscriber. Executions track the progress of each step.

Creating a Workflow

Via Dashboard

1. Navigate to Workflows in the sidebar
2. Click Create Workflow
3. Enter a name (the key is auto-generated from the name)
4. Use the visual Workflow Builder to add steps
5. Activate the workflow when ready

Via API

curl -X POST https://api.zyphr.dev/v1/workflows \
  -H "X-API-Key: zy_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Order Confirmation",
    "key": "order-confirmation",
    "description": "Multi-channel order confirmation with fallback"
  }'

const workflow = await zyphr.workflows.create({
  name: 'Order Confirmation',
  key: 'order-confirmation',
  description: 'Multi-channel order confirmation with fallback',
});

Adding Steps

Via Dashboard

Use the visual Workflow Builder to drag and drop steps onto the canvas. See the Workflow Builder Guide for details.

Via API

# Step 1: In-App notification
curl -X POST https://api.zyphr.dev/v1/workflows/order-confirmation/steps \
  -H "X-API-Key: zy_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "step_key": "send-in-app",
    "name": "Send In-App",
    "type": "in_app",
    "config": {
      "title": "Order {{payload.orderId}} confirmed!",
      "body": "Your order for {{payload.orderTotal}} is on the way.",
      "action_url": "/orders/{{payload.orderId}}"
    }
  }'

# Step 2: Delay 1 hour
curl -X POST https://api.zyphr.dev/v1/workflows/order-confirmation/steps \
  -H "X-API-Key: zy_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "step_key": "wait-1hr",
    "name": "Wait 1 Hour",
    "type": "delay",
    "config": {
      "amount": 1,
      "unit": "hours"
    }
  }'

# Step 3: Branch - check if in-app was read
curl -X POST https://api.zyphr.dev/v1/workflows/order-confirmation/steps \
  -H "X-API-Key: zy_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "step_key": "check-read",
    "name": "Was In-App Read?",
    "type": "branch",
    "config": {
      "conditions": [{
        "source": "step_outcome",
        "step_key": "send-in-app",
        "field": "read",
        "operator": "=",
        "value": true
      }]
    }
  }'

Managing Workflows

Via Dashboard

• Activate/Pause: Toggle the workflow status from the workflow list or detail page
• Edit: Click on a workflow to open the Workflow Builder
• Delete: Click the menu and select Delete
• View Executions: Click on a workflow, then go to the Executions tab

Via API

# List workflows
curl https://api.zyphr.dev/v1/workflows \
  -H "X-API-Key: zy_live_your_key"

# Get workflow details
curl https://api.zyphr.dev/v1/workflows/WORKFLOW_ID \
  -H "X-API-Key: zy_live_your_key"

# Activate a workflow
curl -X POST https://api.zyphr.dev/v1/workflows/WORKFLOW_ID/activate \
  -H "X-API-Key: zy_live_your_key"

# Pause a workflow
curl -X POST https://api.zyphr.dev/v1/workflows/WORKFLOW_ID/pause \
  -H "X-API-Key: zy_live_your_key"

# Delete a workflow
curl -X DELETE https://api.zyphr.dev/v1/workflows/WORKFLOW_ID \
  -H "X-API-Key: zy_live_your_key"

Triggering a Workflow

To a single subscriber

curl -X POST https://api.zyphr.dev/v1/workflows/order-confirmation/trigger \
  -H "X-API-Key: zy_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "user_123",
    "payload": {
      "orderId": "ORD-456",
      "orderTotal": "$49.99"
    }
  }'

To multiple subscribers

curl -X POST https://api.zyphr.dev/v1/workflows/weekly-digest/trigger \
  -H "X-API-Key: zy_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": ["user_123", "user_456", "user_789"],
    "payload": { "weekOf": "2026-02-24" }
  }'

To a topic (fan-out)

curl -X POST https://api.zyphr.dev/v1/workflows/product-update/trigger \
  -H "X-API-Key: zy_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": { "topic": "product-updates" },
    "payload": {
      "featureName": "Notification Workflows",
      "releaseDate": "2026-02-24"
    }
  }'

Monitoring Executions

Via Dashboard

1. Navigate to Workflows and click on a workflow
2. Go to the Executions tab
3. See all executions with their status (pending, running, completed, failed)
4. Click into an execution to see step-by-step progress with timing and results

Via API

# List executions for a workflow
curl "https://api.zyphr.dev/v1/workflows/order-confirmation/executions?page=1&per_page=25" \
  -H "X-API-Key: zy_live_your_key"

# Get execution detail with step-by-step status
curl https://api.zyphr.dev/v1/executions/exec_abc123 \
  -H "X-API-Key: zy_live_your_key"

Template Variables

Step content supports {{variable}} syntax for dynamic content:

• {{payload.fieldName}} — Data from the trigger payload
• {{subscriber.name}} — Subscriber profile fields
• {{subscriber.email}} — Subscriber email
• {{subscriber.metadata.key}} — Subscriber custom metadata

Workflow Status

Status	Description
draft	Being edited, cannot be triggered
active	Ready to receive triggers
paused	Temporarily disabled
archived	Soft-deleted, cannot be triggered

Critical Workflows

Workflows marked as is_critical: true bypass subscriber notification preferences. Use for:

• Account verification
• Password resets
• Security alerts
• Billing notifications

Plan Limits

Plan	Workflows	Branch/Delay Steps
Free	3	No
Starter	10	No
Pro	50	Yes
Scale	200	Yes
Enterprise	Unlimited	Yes

Use Cases

• Order lifecycle: Confirm → ship → deliver with multi-channel fallback
• Onboarding sequences: Welcome email → feature tips (push) → engagement check (in-app)
• Alert escalation: In-app → push → SMS with increasing urgency
• Re-engagement: In-app notification → wait 24h → email if not read