Trigger Workflow

Trigger pre-configured workflows to execute immediately or at a scheduled time. Perfect for onboarding sequences, OTP verification, campaigns, and automated messaging.

Endpoint

POST /api/v1/workflows/trigger

Headers

X-API-Key: sk_live_your_api_key
Content-Type: application/json

Why Use This Endpoint?

🚀 Simple & Fast - Lightweight API, just specify workflow and recipients
🎯 Flexible Targeting - Single contact, tagged groups, or all users
⏰ Schedule Later - Trigger now or schedule for future execution
🔐 Channel-Specific OTPs - Different OTP codes per channel (Email/SMS/WhatsApp)
📊 Auto-Tracking - Built-in execution tracking and analytics
🧪 Template Variables - Pass custom data to personalize messages

Core Concept

This endpoint triggers an existing workflow that you've already created. Think of it as pressing the "start" button on an automated sequence.

Workflow execution flow:

API Request → Queue Workflow → Load Contacts → Execute Steps → Track Results

Request Structure

Required Fields

Field	Type	Description
`workflow_id` OR `workflow_name`	string	Workflow UUID or name (must provide one)
`recipient_type`	string	Who receives: `"contact"`, `"tag"`, or `"all"`

Conditional Fields (based on `recipient_type`)

Field	Type	Required When	Description
`contact_external_id`	string	`recipient_type = "contact"`	Contact's external ID
`tag`	array	`recipient_type = "tag"`	Array of tags (AND logic)

Optional Fields

Field	Type	Description
`trigger_at`	string	ISO 8601 timestamp for scheduled execution
`variables`	object	General variables available in all channel templates
`channel_variables`	object	Channel-specific variables (e.g., different OTPs per channel)

Use Case Examples

Example 1: Trigger for Single Contact

Send a welcome workflow to a newly registered user.

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": "550e8400-e29b-41d4-a716-446655440000",
    "recipient_type": "contact",
    "contact_external_id": "user_12345",
    "variables": {
      "user_name": "John Doe",
      "signup_bonus": "$10"
    }
  }'

Response:

{
  "success": true,
  "trigger_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "job_id": "12345",
  "message": "Workflow trigger queued successfully"
}

Example 2: Trigger by Workflow Name

You can use the workflow name instead of ID for easier integration.

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": "Welcome Series",
    "recipient_type": "contact",
    "contact_external_id": "user_12345"
  }'

Example 3: Multi-Channel OTP Verification

Send different OTP codes via Email, SMS, and WhatsApp in one 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_name": "OTP Verification",
    "recipient_type": "contact",
    "contact_external_id": "user_12345",
    "variables": {
      "user_name": "Alice Johnson",
      "verification_purpose": "account_security"
    },
    "channel_variables": {
      "email": {
        "otp": "123456",
        "verification_url": "https://yourapp.com/verify?code=123456"
      },
      "sms": {
        "otp": "654321"
      },
      "whatsapp": {
        "otp": "789012"
      }
    }
  }'

How it works:

Email template gets: user_name, verification_purpose, otp=123456, verification_url
SMS template gets: user_name, verification_purpose, otp=654321
WhatsApp template gets: user_name, verification_purpose, otp=789012

Example 4: Send to Tagged Contacts

Trigger workflow for all users with "premium" AND "beta" tags.

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": "Premium Beta Features",
    "recipient_type": "tag",
    "tag": ["premium", "beta"],
    "variables": {
      "feature_name": "Advanced Analytics",
      "release_date": "2024-12-15"
    }
  }'

Note: Contacts must have ALL specified tags (AND logic).

Example 5: Send to All Contacts

Broadcast workflow to your entire contact list.

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": "Holiday Greetings",
    "recipient_type": "all",
    "variables": {
      "holiday_name": "Christmas",
      "discount_code": "XMAS2024"
    }
  }'

Example 6: Schedule for Later

Schedule workflow execution for a specific date/time.

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": "Black Friday Campaign",
    "recipient_type": "all",
    "trigger_at": "2024-11-29T00:00:00Z",
    "variables": {
      "sale_percentage": "50%",
      "valid_until": "2024-11-30T23:59:59Z"
    }
  }'

Response:

{
  "success": true,
  "trigger_id": "a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890",
  "job_id": "67890",
  "message": "Workflow trigger queued for 2024-11-29T00:00:00.000Z",
  "scheduled_for": "2024-11-29T00:00:00.000Z"
}

Response Fields

Success Response (201 Created)

Field	Type	Description
`success`	boolean	Always `true` for successful trigger
`trigger_id`	string	UUID of the created trigger (for tracking)
`job_id`	string	Queue job ID
`message`	string	Human-readable status message
`scheduled_for`	string	ISO timestamp (only if `trigger_at` was provided)

Error Response (4xx)

{
  "statusCode": 400,
  "message": "Error description",
  "error": "Bad Request"
}

Common Error Responses

Status Code	Error Message	Cause	Solution
400	Either workflow_id or workflow_name must be provided	Missing workflow identifier	Provide `workflow_id` OR `workflow_name`
400	Invalid trigger_at format	Malformed timestamp	Use ISO 8601 format (e.g., `2024-12-25T10:00:00Z`)
400	trigger_at must be a future date	Past timestamp provided	Use future date/time
404	Workflow [id/name] not found	Invalid workflow identifier	Check workflow exists and ID/name is correct
401	Unauthorized	Invalid or missing API key	Check X-API-Key header

Variables Deep Dive

General Variables

Available in ALL channel templates for this workflow:

{
  "variables": {
    "user_name": "John Doe",
    "order_id": "ORD-12345",
    "company_name": "Acme Inc",
    "support_email": "support@example.com"
  }
}

Usage in templates:

Hello {{user_name}},

Your order {{order_id}} has been confirmed!

Contact us: {{support_email}}

Channel-Specific Variables

Override variables per channel (highest priority):

{
  "channel_variables": {
    "email": {
      "otp": "123456",
      "verification_url": "https://app.com/verify?code=123456",
      "button_text": "Verify Email"
    },
    "sms": {
      "otp": "654321"
    },
    "whatsapp": {
      "otp": "789012",
      "support_link": "https://wa.me/1234567890"
    }
  }
}

Variable Merge Priority:

General variables (lowest)
Workflow context
Step configuration variables
Channel-specific variables (highest priority) ⭐

Auto-Added Variables

These are automatically available in all templates:

{
  "workflow": {
    "id": "workflow-uuid",
    "name": "Welcome Series",
    "step_name": "Day 1 Welcome Email"
  },
  "event": {
    "type": "manual_trigger",
    "id": "event-uuid"
  }
}

Usage:

You're receiving this as part of our {{workflow.name}}.

Workflow Execution Tracking

After triggering, track execution progress:

Get Trigger Status

GET /api/v1/triggers/:trigger_id

Get Workflow Executions

GET /api/v1/workflows/:workflow_id

Response includes:

Total contacts processed
Messages sent per channel
Delivery rates
Costs
Current execution status

Best Practices

1. Use Workflow Name for Readability

{
  "workflow_name": "Welcome Series",  // ✅ Easy to read
  "recipient_type": "contact"
}

Instead of:

{
  "workflow_id": "550e8400-e29b-41d4-a716-446655440000",  // ❌ Hard to manage
  "recipient_type": "contact"
}

2. Organize Variables

{
  "variables": {
    // User data
    "user_name": "John",
    "user_email": "john@example.com",

    // Order data
    "order_id": "12345",
    "order_total": "$99.99",

    // Configuration
    "support_email": "help@example.com"
  }
}

3. Security - Different OTPs per Channel

{
  "channel_variables": {
    "email": { "otp": generateOTP() },    // "123456"
    "sms": { "otp": generateOTP() },      // "654321"
    "whatsapp": { "otp": generateOTP() }  // "789012"
  }
}

This provides multi-factor authentication - user must verify via their preferred channel.

4. Test with Single Contact First

{
  "workflow_name": "New Campaign",
  "recipient_type": "contact",
  "contact_external_id": "test_user_123"  // ✅ Test first
}

Then scale to all:

{
  "workflow_name": "New Campaign",
  "recipient_type": "all"  // ✅ After testing
}

5. Handle Scheduled Triggers

const scheduledTime = new Date('2024-12-25T10:00:00Z');

if (scheduledTime < new Date()) {
  throw new Error('Cannot schedule in the past');
}

await triggerWorkflow({
  workflow_name: 'Holiday Greetings',
  recipient_type: 'all',
  trigger_at: scheduledTime.toISOString()
});

6. Error Handling

try {
  const response = await fetch('/api/v1/workflows/trigger', {
    method: 'POST',
    headers: {
      'X-API-Key': apiKey,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      workflow_name: 'Welcome Series',
      recipient_type: 'contact',
      contact_external_id: userId
    })
  });

  const data = await response.json();

  if (!response.ok) {
    if (response.status === 404) {
      console.error('Workflow not found');
    } else if (response.status === 400) {
      console.error('Invalid request:', data.message);
    }
    throw new Error(data.message);
  }

  console.log('Workflow triggered:', data.trigger_id);

} catch (error) {
  console.error('Failed to trigger workflow:', error);
}

Rate Limits

This endpoint is subject to rate limiting based on your account plan:

Starter: 100 requests per hour
Pro: 1000 requests per hour
Enterprise: Custom limits

Exceeding limits returns 429 Too Many Requests.

Next Steps

Get Workflow Details - View workflow configuration and statistics
List Workflows - Browse all workflows
Create Workflow - Build custom workflows
Workflows Overview - Learn core concepts

POST /api/v1/workflows/send - Advanced workflow trigger with full payload control
GET /api/v1/workflows/:id - Get workflow details and stats
GET /api/v1/triggers/:id - Get trigger execution status

Endpoint​

Headers​

Why Use This Endpoint?​

Core Concept​

Request Structure​

Required Fields​

Conditional Fields (based on recipient_type)​

Optional Fields​

Use Case Examples​

Example 1: Trigger for Single Contact​

Example 2: Trigger by Workflow Name​

Example 3: Multi-Channel OTP Verification​

Example 4: Send to Tagged Contacts​

Example 5: Send to All Contacts​

Example 6: Schedule for Later​

Response Fields​

Success Response (201 Created)​

Error Response (4xx)​

Common Error Responses​

Variables Deep Dive​

General Variables​

Channel-Specific Variables​

Auto-Added Variables​

Workflow Execution Tracking​

Get Trigger Status​

Get Workflow Executions​

Best Practices​

1. Use Workflow Name for Readability​

2. Organize Variables​

3. Security - Different OTPs per Channel​

4. Test with Single Contact First​

5. Handle Scheduled Triggers​

6. Error Handling​

Rate Limits​

Next Steps​

Related Endpoints​