Send SMS API

Send SMS messages to specific recipients, contacts, tags, or all contacts. Supports template-based messaging with variable substitution and optional scheduling.

Endpoint

POST /api/v1/sms/send

Headers

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

Quick Example

curl -X POST https://api.sendmator.com/api/v1/sms/send \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "template_key": "otp-sms",
    "recipient_type": "direct_sms",
    "direct_phone": "+1234567890",
    "variables": {
      "otp_code": "123456"
    }
  }'

Request Parameters

Required Fields

Field	Type	Description
`template_key`	string	SMS template identifier to use
`recipient_type`	string	How to target recipients: `direct_sms`, `contact`, `tag`, `all`

Recipient-Specific Fields

Recipient Type	Required Field	Type	Description
`direct_sms`	`direct_phone`	string	Phone number in E.164 format (e.g., `+1234567890`)
`contact`	`contact_external_id`	string	External ID of the contact
`tag`	`tag`	string[]	Array of tags to match
`all`	(none)	-	Sends to all active contacts with SMS opt-in

Optional Fields for Direct SMS

Field	Type	Description
`direct_first_name`	string	Recipient's first name (for personalization)
`direct_last_name`	string	Recipient's last name (for personalization)

Common Optional Fields

Field	Type	Description
`variables`	object	Template variables (key-value pairs)
`metadata`	object	Custom tracking data
`triggerAt`	string	ISO 8601 UTC timestamp for scheduled send
`sms_identity_id`	string	SMS identity UUID (defaults to user's default)

Complete Examples

1. Send Direct SMS with OTP

Send to a specific phone number without requiring a contact record:

curl -X POST https://api.sendmator.com/api/v1/sms/send \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "template_key": "otp-sms",
    "recipient_type": "direct_sms",
    "direct_phone": "+1234567890",
    "direct_first_name": "John",
    "variables": {
      "otp_code": "123456",
      "app_name": "MyApp"
    }
  }'

Response:

{
  "success": true,
  "trigger_id": "550e8400-e29b-41d4-a716-446655440000",
  "job_id": "123",
  "message": "SMS queued successfully"
}

Use Cases:

OTP verification
One-time notifications
Messages to non-registered users
Quick transactional SMS

2. Send to Contact

Send to a specific contact using their external ID:

curl -X POST https://api.sendmator.com/api/v1/sms/send \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "template_key": "order-confirmation",
    "recipient_type": "contact",
    "contact_external_id": "user-123",
    "variables": {
      "order_id": "ORD-456",
      "delivery_date": "March 15, 2026"
    }
  }'

Response:

{
  "success": true,
  "trigger_id": "abc123-def456-ghi789",
  "job_id": "124",
  "message": "SMS queued successfully"
}

Use Cases:

Order confirmations
Account notifications
User-specific updates
Personalized alerts

Auto-populated Variables: When sending to a contact, their data is automatically available:

{{contact_first_name}} - Contact's first name
{{contact_last_name}} - Contact's last name
{{contact_phone}} - Contact's phone number
{{contact_external_id}} - Contact's external ID

3. Send to Tagged Contacts

Send to all contacts with specific tags:

curl -X POST https://api.sendmator.com/api/v1/sms/send \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "template_key": "flash-sale",
    "recipient_type": "tag",
    "tag": ["premium", "vip"],
    "variables": {
      "sale_discount": "50%",
      "sale_end_time": "6 PM today"
    }
  }'

Response:

{
  "success": true,
  "trigger_id": "pqr901-stu234-vwx567",
  "job_id": "125",
  "message": "SMS queued successfully"
}

Use Cases:

Targeted promotions
Segment-specific campaigns
VIP notifications
Customer tier-based messaging

4. Send to All Contacts

Broadcast to all active contacts with SMS opt-in:

curl -X POST https://api.sendmator.com/api/v1/sms/send \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "template_key": "system-announcement",
    "recipient_type": "all",
    "variables": {
      "announcement": "System maintenance tonight at 2 AM",
      "company_name": "MyApp"
    }
  }'

Response:

{
  "success": true,
  "trigger_id": "xyz789-abc123-mno456",
  "job_id": "126",
  "message": "SMS queued successfully"
}

Use Cases:

System maintenance notifications
Emergency communications
Major announcements
Company-wide updates

5. Scheduled SMS

Schedule an SMS for future delivery:

curl -X POST https://api.sendmator.com/api/v1/sms/send \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "template_key": "appointment-reminder",
    "recipient_type": "contact",
    "contact_external_id": "user-123",
    "variables": {
      "appointment_date": "March 20, 2026",
      "appointment_time": "2:00 PM"
    },
    "triggerAt": "2026-03-19T14:00:00Z"
  }'

Response:

{
  "success": true,
  "trigger_id": "lmn012-opq345-rst678",
  "job_id": "127",
  "message": "SMS scheduled successfully",
  "scheduled_for": "2026-03-19T14:00:00Z",
  "delay_ms": 86400000
}

Use Cases:

Appointment reminders
Time-zone specific sends
Scheduled campaigns
Event notifications

Response Format

Success Response (201 Created)

{
  "success": true,
  "trigger_id": "550e8400-e29b-41d4-a716-446655440000",
  "job_id": "123",
  "message": "SMS queued successfully"
}

Field	Type	Description
`success`	boolean	Always `true` for successful requests
`trigger_id`	string	Unique ID to track this send operation
`job_id`	string	Job queue ID for monitoring
`message`	string	Human-readable status message

Error Responses

Missing Template (400)

{
  "statusCode": 400,
  "message": "Template 'otp-sms' not found for team",
  "error": "Bad Request"
}

Contact Not Found (404)

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

Insufficient Balance (400)

{
  "statusCode": 400,
  "message": "Insufficient wallet balance. Required: 10.50 USD, Available: 5.00 USD. Please recharge your wallet to continue.",
  "error": "Bad Request"
}

Invalid Phone Format (400)

{
  "statusCode": 400,
  "message": "direct_phone must be in E.164 format (e.g., +1234567890)",
  "error": "Bad Request"
}

SMS Templates

All SMS messages require a template. Templates must be created in the Sendmator dashboard before sending.

Template Variables

Use double curly braces for variable substitution:

Your OTP code is {{otp_code}}. Valid for 10 minutes. -{{company_name}}

Character Limits

Single SMS: 160 characters
Multi-part SMS: Automatically split (charged per segment)
Unicode characters: Reduce limit to 70 characters per segment

DLT Compliance (India)

For Indian numbers, templates must be:

Registered with DLT (Distributed Ledger Technology)
Approved by telecom operators
Include proper sender ID and template ID

Recipient Types Summary

Type	Description	Required Field	Use Case
`direct_sms`	Send to phone number	`direct_phone`	OTP, one-time messages
`contact`	Send to existing contact	`contact_external_id`	Personalized messages
`tag`	Send to tagged contacts	`tag` (array)	Targeted campaigns
`all`	Send to all contacts	(none)	Broadcasts

Subscription Management

Sendmator automatically handles SMS subscription preferences:

Opt-in: Only contacts who have opted in receive SMS
Opt-out: Automatically filtered from recipient list
Compliance: Ensures adherence to SMS marketing regulations

Users can opt-out by replying "STOP" to any SMS.

Pricing

SMS pricing varies by destination country:

Region	Price per SMS
USA/Canada	~$0.0075
UK	~$0.04
India	~$0.0035
Australia	~$0.05
Other	Varies

Note: Multi-part messages are charged per segment.

Best Practices

1. Keep Messages Concise

# ✅ Good: Clear, concise message under 160 characters
{
  "template_key": "otp-short",
  "variables": {
    "otp_code": "123456"
  }
}
# Message: "Your OTP: 123456. Valid for 10 minutes."

# ❌ Avoid: Long messages that split into multiple parts
# Message: "Hello! Your one-time password for logging into your account is 123456..."

2. Use Appropriate Templates

# ✅ Good: Transactional messages for OTP
{
  "template_key": "otp-verification",
  "recipient_type": "direct_sms"
}

# ⚠️ Marketing requires opt-in
{
  "template_key": "promotional-offer",
  "recipient_type": "tag",
  "tag": ["marketing-opt-in"]
}

3. Include Opt-Out Information

All marketing SMS should include opt-out instructions:

Get 50% off today! Reply STOP to unsubscribe.

4. Test Before Broadcasting

# Step 1: Test with yourself
{
  "recipient_type": "direct_sms",
  "direct_phone": "+your-phone"
}

# Step 2: Test with small group
{
  "recipient_type": "tag",
  "tag": ["internal-team"]
}

# Step 3: Send to everyone
{
  "recipient_type": "all"
}

Multi-Channel Messages

To send messages across multiple channels (Email, SMS, WhatsApp, Push) simultaneously, use the Multi-Channel Trigger API instead of /sms/send.

Next Steps

Create SMS Templates - Set up reusable SMS templates
Manage Contacts - Build your contact database
Multi-Channel API - Send across multiple channels
API Overview - Explore other endpoints

Endpoint​

Headers​

Quick Example​

Request Parameters​

Required Fields​

Recipient-Specific Fields​

Optional Fields for Direct SMS​

Common Optional Fields​

Complete Examples​

1. Send Direct SMS with OTP​

2. Send to Contact​

3. Send to Tagged Contacts​

4. Send to All Contacts​

5. Scheduled SMS​

Response Format​

Success Response (201 Created)​

Error Responses​

Missing Template (400)​

Contact Not Found (404)​

Insufficient Balance (400)​

Invalid Phone Format (400)​

SMS Templates​

Template Variables​

Character Limits​

DLT Compliance (India)​

Recipient Types Summary​

Subscription Management​

Pricing​

Best Practices​

1. Keep Messages Concise​

2. Use Appropriate Templates​

3. Include Opt-Out Information​

4. Test Before Broadcasting​

Multi-Channel Messages​

Next Steps​

Endpoint

Headers

Quick Example

Request Parameters

Required Fields

Recipient-Specific Fields

Optional Fields for Direct SMS

Common Optional Fields

Complete Examples

1. Send Direct SMS with OTP

2. Send to Contact

3. Send to Tagged Contacts

4. Send to All Contacts

5. Scheduled SMS

Response Format

Success Response (201 Created)

Error Responses

Missing Template (400)

Contact Not Found (404)

Insufficient Balance (400)

Invalid Phone Format (400)

SMS Templates

Template Variables

Character Limits

DLT Compliance (India)

Recipient Types Summary

Subscription Management

Pricing

Best Practices

1. Keep Messages Concise

2. Use Appropriate Templates

3. Include Opt-Out Information

4. Test Before Broadcasting

Multi-Channel Messages

Next Steps