Skip to main content

Workflows API Overview

Automate multi-channel messaging sequences with event-driven workflows. Send coordinated campaigns across Email, SMS, and WhatsApp with custom timing, conditions, and personalization.

What are Workflows?​

Workflows are automated, multi-step messaging sequences that execute when triggered. They allow you to:

  • 📧 Multi-Channel Campaigns - Coordinate Email, SMS, and WhatsApp in one workflow
  • ⏰ Timed Sequences - Add delays between steps (e.g., email → wait 1 day → SMS)
  • 🎯 Smart Targeting - Send to specific contacts, tags, or all users
  • 🔄 Event-Driven - Trigger automatically based on user actions or API calls
  • 📊 Track Performance - Monitor delivery, engagement, and costs across all channels
  • 🧪 Channel-Specific Variables - Use different OTPs or content per channel

How Workflows Work​

┌─────────────────┐
│   1. Trigger    │  API call or event triggers workflow
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  2. Load Steps  │  Workflow steps execute in sequence
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  3. Execute     │  Send messages across channels
│     Steps       │  Email → delay → SMS → delay → WhatsApp
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  4. Track &     │  Monitor delivery, engagement, costs
│     Report      │
└─────────────────┘

Available Endpoints​

EndpointMethodDescription
/api/v1/workflows/triggerPOSTTrigger workflow - Simple API to trigger a workflow for contacts
/api/v1/workflows/sendPOSTSend workflow - Advanced workflow trigger with full control
/api/v1/workflowsPOSTCreate a new event-driven workflow
/api/v1/workflowsGETList all workflows with filtering
/api/v1/workflows/:idGETGet workflow details with statistics
/api/v1/workflows/:idPATCHUpdate workflow configuration
/api/v1/workflows/:idDELETEDelete a workflow
/api/v1/workflows/:id/executionsGETGet execution history for a workflow

Core Concepts​

1. Workflow Trigger​

Triggers determine when a workflow executes. Two methods:

  • API Trigger - Manually trigger via API call (most common)
  • Event Trigger - Automatically trigger based on user events (coming soon)

2. Recipient Types​

Choose who receives the workflow:

TypeDescriptionUse Case
contactSingle contact by external IDVerify specific user
tagAll contacts with specific tags (AND logic)Send to "premium" + "beta" users
allAll contacts in your accountNewsletters, announcements

3. Workflow Steps​

Each workflow consists of steps that execute sequentially:

{
  "step_order": 1,
  "channel_type": "email",
  "configuration": {
    "template_id": "welcome-email",
    "delay_minutes": 0,
    "variables": {
      "welcome_bonus": "$10"
    }
  }
}

Step delay: Steps can have delays (e.g., wait 24 hours before next step)

4. Variables & Channel Variables​

General Variables apply to all steps:

{
  "variables": {
    "user_name": "John",
    "company": "Acme Inc"
  }
}

Channel-Specific Variables override per channel (perfect for different OTPs):

{
  "channel_variables": {
    "email": { "otp": "123456" },
    "sms": { "otp": "654321" },
    "whatsapp": { "otp": "789012" }
  }
}

5. Workflow Execution​

When you trigger a workflow:

  1. Trigger created - Request accepted, trigger ID returned
  2. Steps queued - Workflow steps added to processing queue
  3. Messages sent - Each step sends to appropriate channel
  4. Tracking updated - Delivery, engagement, and costs tracked

Execution Status:

  • PENDING - Waiting to start
  • PROCESSING - Currently executing
  • COMPLETED - All steps finished
  • FAILED - Execution failed
  • SCHEDULED - Delayed for future execution

Quick Start​

1. Trigger a Simple Workflow​

curl -X POST https://api.sendmator.com/api/v1/workflows/trigger \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_id": "your-workflow-uuid",
    "recipient_type": "contact",
    "contact_external_id": "user_123",
    "variables": {
      "user_name": "John Doe"
    }
  }'

2. Trigger with Channel-Specific OTPs​

curl -X POST https://api.sendmator.com/api/v1/workflows/trigger \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_name": "OTP Verification",
    "recipient_type": "contact",
    "contact_external_id": "user_123",
    "variables": {
      "user_name": "John Doe"
    },
    "channel_variables": {
      "email": { "otp": "123456" },
      "sms": { "otp": "654321" },
      "whatsapp": { "otp": "789012" }
    }
  }'

3. Schedule for Later​

curl -X POST https://api.sendmator.com/api/v1/workflows/trigger \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_id": "your-workflow-uuid",
    "recipient_type": "all",
    "trigger_at": "2024-12-25T10:00:00Z"
  }'

Common Use Cases​

1. User Onboarding Sequence​

Day 0: Welcome Email
Day 1: Getting Started Guide (Email)
Day 3: Feature Highlights (SMS)
Day 7: Success Stories (WhatsApp)

2. Multi-Channel OTP Verification​

Send different OTP codes to Email, SMS, and WhatsApp for maximum security.

3. Abandoned Cart Recovery​

1 Hour: Reminder Email
24 Hours: SMS with discount code
48 Hours: WhatsApp with limited offer

4. Event Announcements​

Trigger workflow to send immediate notifications across all channels.

Best Practices​

1. Variable Organization​

  • General variables - User info, order details, common data
  • Channel variables - Channel-specific OTPs, URLs, formatting

2. Error Handling​

Always handle response codes:

  • 201 - Success, trigger created
  • 400 - Invalid request
  • 404 - Workflow not found
  • 401 - Authentication error

3. Testing​

Use a test workflow with a single contact before sending to all users.

4. Rate Limiting​

Workflows respect rate limits per channel. Large campaigns may take time to complete.

5. Monitoring​

Check workflow execution status:

GET /api/v1/workflows/:workflow_id

Next Steps​

Authentication​

All workflow endpoints require authentication via API Key:

X-API-Key: sk_live_your_api_key

Get your API key from your Sendmator dashboard.