Multi-Channel Trigger API

Send messages across multiple channels (Email, SMS, WhatsApp, Push) simultaneously with a single API call. Perfect for omnichannel campaigns and important notifications.

Endpoint

POST /api/v1/messages/trigger

Headers

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

Overview

The Multi-Channel Trigger API allows you to send messages across multiple channels in one request. Each channel execution is tracked separately, giving you detailed analytics per channel.

Key Features:

Send to multiple channels simultaneously
Separate execution tracking per channel
Channel-specific template support
Unified trigger management
Individual channel analytics

Quick Example

curl -X POST https://api.sendmator.com/api/v1/messages/trigger \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient_type": "contact",
    "contact_external_id": "user-123",
    "channels": ["email", "sms", "push"],
    "template_key": "welcome",
    "push_title": "Welcome!",
    "push_body": "Thanks for joining us",
    "variables": {
      "name": "John Doe",
      "company": "Acme Corp"
    }
  }'

Request Parameters

Required Fields

Field	Type	Description
`recipient_type`	string	How to target recipients: `contact`, `tag`, `segment`, `all`
`channels`	string[]	Array of channels to send on: `["email", "sms", "whatsapp", "push"]`

Recipient-Specific Fields

Recipient Type	Required Field	Type	Description
`contact`	`contact_external_id`	string	External ID of the contact
`tag`	`tags`	string[]	Array of tags to match
`segment`	`segment_id`	string	Segment ID from dashboard
`all`	(none)	-	Sends to all active contacts

Template Configuration

Use the template_key field to specify which template to use:

{
  "template_key": "welcome"
}

Note: The same template key is used across all channels. Each channel will use its own template type (email template for email channel, SMS template for SMS channel, etc.).

Optional Fields

Field	Type	Description
`variables`	object	Template variables (key-value pairs) - shared across all channels
`metadata`	object	Custom tracking data
`trigger_at`	string	ISO 8601 UTC timestamp for scheduled send
`from_email`	string	Override sender email address (email channel only)
`from_name`	string	Override sender name (email channel only)

Complete Examples

1. Send to Contact Across All Channels

curl -X POST https://api.sendmator.com/api/v1/messages/trigger \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient_type": "contact",
    "contact_external_id": "user-123",
    "channels": ["email", "sms", "whatsapp", "push"],
    "template_key": "order-confirmation",
    "push_title": "Order Confirmed!",
    "push_body": "Your order ORD-456 has been confirmed",
    "variables": {
      "order_id": "ORD-456",
      "order_total": "$99.99",
      "delivery_date": "March 15, 2026"
    }
  }'

Response:

{
  "success": true,
  "trigger_id": "abc123-def456-ghi789",
  "message": "Multi-channel trigger created successfully",
  "channels_triggered": ["email", "sms", "whatsapp", "push"]
}

Use Cases:

Critical order confirmations
Account security alerts
Important announcements
Time-sensitive notifications

2. Send to All Contacts on Email + SMS

curl -X POST https://api.sendmator.com/api/v1/messages/trigger \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient_type": "all",
    "channels": ["email", "sms"],
    "template_key": "product-launch",
    "variables": {
      "product_name": "New Widget Pro",
      "launch_date": "April 1, 2026",
      "discount_code": "LAUNCH20"
    }
  }'

Response:

{
  "success": true,
  "trigger_id": "xyz789-abc123-def456",
  "message": "Multi-channel trigger created successfully",
  "channels_triggered": ["email", "sms"]
}

Use Cases:

Product launches
System maintenance announcements
Major company updates
Emergency communications

3. Send to Tagged Contacts (Scheduled)

curl -X POST https://api.sendmator.com/api/v1/messages/trigger \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient_type": "tag",
    "tags": ["premium", "beta"],
    "channels": ["email", "push"],
    "template_key": "beta-feature",
    "push_title": "New Beta Feature!",
    "push_body": "AI Assistant beta starts March 20",
    "variables": {
      "feature_name": "AI Assistant",
      "beta_start_date": "March 20, 2026"
    },
    "trigger_at": "2026-03-15T10:00:00Z"
  }'

Response:

{
  "success": true,
  "trigger_id": "pqr901-stu234-vwx567",
  "message": "Multi-channel trigger scheduled successfully",
  "channels_triggered": ["email", "push"],
  "scheduled_for": "2026-03-15T10:00:00Z"
}

Use Cases:

Beta feature rollouts
VIP early access
Segment-specific campaigns
Scheduled announcements

4. Send to Segment with Metadata

curl -X POST https://api.sendmator.com/api/v1/messages/trigger \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient_type": "segment",
    "segment_id": "seg-active-users-30d",
    "channels": ["email", "sms", "whatsapp"],
    "template_key": "winback",
    "variables": {
      "special_offer": "30% off",
      "expiry_date": "March 31, 2026"
    },
    "metadata": {
      "campaign_id": "winback-q1-2026",
      "campaign_type": "retention",
      "ab_variant": "multi-channel"
    }
  }'

Response:

{
  "success": true,
  "trigger_id": "lmn012-opq345-rst678",
  "message": "Multi-channel trigger created successfully",
  "channels_triggered": ["email", "sms", "whatsapp"]
}

Use Cases:

Re-engagement campaigns
Win-back campaigns
Targeted promotions
Behavioral triggers

Channel-Specific Behavior

Email

Requires approved email template
Subject line from template
HTML and plain text versions
Email tracking (opens, clicks, bounces)
Unsubscribe links automatically added

SMS

Requires country-approved SMS template
Character limits apply (160 chars for single SMS)
Automatic link shortening
Delivery receipts tracked
Cost calculated per message segment

Requires Meta-approved WhatsApp template
Template category must match use case
Media attachments supported (if template includes)
Read receipts tracked
24-hour session window rules apply

Push

Requires active push subscription
Device token must be valid
Title and body from template
Deep linking supported
Click-through tracking
Works across web, iOS, Android

Response Format

Success Response (200 OK)

{
  "success": true,
  "trigger_id": "abc123-def456-ghi789",
  "message": "Multi-channel trigger created successfully",
  "channels_triggered": ["email", "sms", "whatsapp", "push"]
}

Field	Type	Description
`success`	boolean	Always `true` for successful requests
`trigger_id`	string	Unique ID to track this multi-channel trigger
`message`	string	Human-readable status message
`channels_triggered`	string[]	Array of channels that were triggered

Error Responses

Invalid Channel (400)

{
  "statusCode": 400,
  "message": "Invalid channel: 'slack'. Valid channels are: email, sms, whatsapp, push",
  "error": "Bad Request"
}

Missing Templates (400)

{
  "statusCode": 400,
  "message": "Template must be provided for all channels. Missing templates for: sms, whatsapp",
  "error": "Bad Request"
}

Contact Not Found (404)

{
  "statusCode": 404,
  "message": "Contact with external_id 'user-123' not found",
  "error": "Not Found"
}

Template Not Found (404)

{
  "statusCode": 404,
  "message": "Template 'welcome-sms' not found for channel: sms",
  "error": "Not Found"
}

Tracking Multi-Channel Executions

After triggering a multi-channel send, use the Trigger API to track status:

# Step 1: Get basic trigger info
GET /api/v1/triggers/{trigger_id}

# Step 2: Get detailed multi-channel execution info
GET /api/v1/triggers/{trigger_id}/direct

Multi-Channel Response Structure:

{
  "trigger_id": "abc123...",
  "flow_type": "direct_channel",
  "channel": "multi_channel",
  "executions": [
    {
      "channel": "email",
      "execution": {
        "id": "exec-email-123",
        "status": "completed",
        "total_contacts": 1000,
        "sent_count": 995,
        "failed_count": 5,
        "filtered_count": 0
      },
      "jobs_endpoint": "/api/v1/messages/executions/exec-email-123/jobs"
    },
    {
      "channel": "sms",
      "execution": {
        "id": "exec-sms-456",
        "status": "completed",
        "total_contacts": 800,
        "sent_count": 795,
        "failed_count": 5,
        "filtered_count": 0
      },
      "jobs_endpoint": "/api/v1/sms/executions/exec-sms-456/jobs"
    }
  ]
}

See Trigger API Documentation for full details.

Best Practices

1. Choose Appropriate Channels

# ✅ Good: Use channels where contacts have opted in
{
  "channels": ["email", "sms"],  # Only channels user subscribed to
}

# ❌ Avoid: Spamming all channels for non-critical messages
{
  "channels": ["email", "sms", "whatsapp", "push"]  # Overkill for newsletter
}

Guidelines:

Critical alerts: All channels (email + sms + whatsapp + push)
Transactional: 2-3 channels (email + sms OR email + push)
Marketing: 1-2 channels (email OR email + push)
Informational: 1 channel (email OR push)

2. Create Channel-Appropriate Templates

Each channel should have its own template optimized for that medium:

Email: Long-form content with images and rich formatting
SMS: Brief text with clear CTA and short links
WhatsApp: Conversational tone following Meta guidelines
Push: Short title (10-15 words) and body (30-40 words)

Create separate templates for each channel with the same template key (e.g., "order-confirmation" for email, SMS, WhatsApp, and push templates).

3. Respect Channel Characteristics

Email:

Detailed information with formatting
Multiple CTAs
Images and branding
Longer messages accepted

SMS:

Keep under 160 characters when possible
Single clear CTA
Include short links
Urgent/time-sensitive info

WhatsApp:

Follow Meta's template guidelines
Use approved templates only
Rich media when appropriate
Conversational tone

Push:

10-15 words max for title
30-40 words max for body
Clear action
Time-sensitive content

4. Test Before Broadcasting

# Step 1: Test with yourself
{
  "recipient_type": "contact",
  "contact_external_id": "your-test-user",
  "channels": ["email", "sms", "push"]
}

# Step 2: Test with small segment
{
  "recipient_type": "tag",
  "tags": ["internal-team"],
  "channels": ["email", "sms", "push"]
}

# Step 3: Full send
{
  "recipient_type": "all",
  "channels": ["email", "sms", "push"]
}

5. Monitor Per-Channel Performance

Each channel in a multi-channel trigger is tracked separately:

# Get overall trigger status
GET /api/v1/triggers/{trigger_id}

# Get detailed per-channel stats
GET /api/v1/triggers/{trigger_id}/direct

# Analyze which channels performed best
# - Email: High open/click rates
# - SMS: High delivery rates
# - Push: High CTR
# - WhatsApp: High read rates

Cost Considerations

Multi-channel triggers cost per channel:

Channel	Cost Calculation
Email	~$0.00 per email (included in most plans)
SMS	Per message segment (varies by country)
WhatsApp	Per conversation/message (varies by template type)
Push	~$0.00 per notification (included in most plans)

Example Cost Breakdown:

Sending to 1,000 contacts across all 4 channels:

Email: $0.00 (included)
SMS: ~$30 (at $0.03/message)
WhatsApp: ~$15-50 (varies by type)
Push: $0.00 (included)

Total: ~$45-80 per 1,000 contacts

Rate Limits

Plan	API Calls/Minute	Max Channels per Trigger
Free	10	2
Pro	100	4
Plus	500	4
Enterprise	Custom	4

Next Steps

Trigger API - Track multi-channel execution status
Email API - Single-channel email sending
SMS API - Single-channel SMS sending
Templates - Create channel-specific templates
Contacts - Manage your contact database

Endpoint​

Headers​

Overview​

Quick Example​

Request Parameters​

Required Fields​

Recipient-Specific Fields​

Template Configuration​

Optional Fields​

Complete Examples​

1. Send to Contact Across All Channels​

2. Send to All Contacts on Email + SMS​

3. Send to Tagged Contacts (Scheduled)​

4. Send to Segment with Metadata​

Channel-Specific Behavior​

Email​

SMS​

WhatsApp​

Push​

Response Format​

Success Response (200 OK)​

Error Responses​

Invalid Channel (400)​

Missing Templates (400)​

Contact Not Found (404)​

Template Not Found (404)​

Tracking Multi-Channel Executions​

Best Practices​

1. Choose Appropriate Channels​

2. Create Channel-Appropriate Templates​

3. Respect Channel Characteristics​

4. Test Before Broadcasting​

5. Monitor Per-Channel Performance​

Cost Considerations​

Rate Limits​

Next Steps​

Endpoint

Headers

Overview

Quick Example

Request Parameters

Required Fields

Recipient-Specific Fields

Template Configuration

Optional Fields

Complete Examples

1. Send to Contact Across All Channels

2. Send to All Contacts on Email + SMS

3. Send to Tagged Contacts (Scheduled)

4. Send to Segment with Metadata

Channel-Specific Behavior

Email

SMS

WhatsApp

Push

Response Format

Success Response (200 OK)

Error Responses

Invalid Channel (400)

Missing Templates (400)

Contact Not Found (404)

Template Not Found (404)

Tracking Multi-Channel Executions

Best Practices

1. Choose Appropriate Channels

2. Create Channel-Appropriate Templates

3. Respect Channel Characteristics

4. Test Before Broadcasting

5. Monitor Per-Channel Performance

Cost Considerations

Rate Limits

Next Steps