SMS

Send SMS text messages through Zyphr's SMS API with multi-provider support and automatic failover. You can send messages via the API and manage SMS configuration through the Dashboard.

Features

• Multi-Provider Fallback - Configure multiple SMS providers with automatic failover
• Global Reach - Send to phone numbers worldwide
• Delivery Tracking - Real-time status updates and webhooks
• Segment Counting - Automatic message segment calculation
• Number Formatting - E.164 format validation and normalization
• Health Monitoring - Circuit breaker pattern with per-provider health tracking

Quick Start

Send an SMS

curl -X POST https://api.zyphr.dev/v1/sms \
  -H "X-API-Key: zy_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155551234",
    "body": "Your verification code is 123456"
  }'

Using Node.js SDK

import { Zyphr } from '@zyphr-dev/node-sdk';

const zyphr = new Zyphr({ apiKey: process.env.ZYPHR_API_KEY });

const sms = await zyphr.sms.send({
  to: '+14155551234',
  body: 'Your verification code is 123456',
});

console.log(`SMS sent: ${sms.id}, segments: ${sms.segments}`);

SMS Parameters

Parameter	Type	Required	Description
to	string	Yes	Recipient phone number (E.164 format)
body	string	Yes	Message text (max 1600 chars)
tags	string[]	No	Tags for filtering/analytics
metadata	object	No	Custom metadata
scheduled_for	string	No	ISO 8601 datetime to schedule send

Phone Number Format

All phone numbers must be in E.164 format:

+[country code][number]

Examples:

• US: +14155551234
• UK: +442071234567
• Germany: +4915123456789

The API will attempt to normalize numbers, but E.164 is recommended.

Message Segments

SMS messages are split into segments based on character encoding:

Encoding	Characters per Segment
GSM-7 (ASCII)	160 (single) / 153 (multi)
UCS-2 (Unicode)	70 (single) / 67 (multi)

The API response includes the segment count:

{
  "data": {
    "id": "sms_abc123",
    "to": "+14155551234",
    "body": "Your code is 123456",
    "segments": 1,
    "status": "queued"
  }
}

Batch Sending

Send to multiple recipients:

curl -X POST https://api.zyphr.dev/v1/sms/batch \
  -H "X-API-Key: zy_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": ["+14155551234", "+14155555678", "+14155559012"],
    "body": "Flash sale! 50% off today only."
  }'

const result = await zyphr.sms.sendBatch({
  to: ['+14155551234', '+14155555678', '+14155559012'],
  body: 'Flash sale! 50% off today only.',
});

console.log(`Sent: ${result.messages.length}, Failed: ${result.failed.length}`);

Batch Limits

Maximum 100 recipients per batch request.

Scheduled SMS

Schedule an SMS for later delivery:

curl -X POST https://api.zyphr.dev/v1/sms \
  -H "X-API-Key: zy_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155551234",
    "body": "Your appointment is tomorrow at 2pm",
    "scheduled_for": "2024-01-16T09:00:00Z"
  }'

await zyphr.sms.send({
  to: '+14155551234',
  body: 'Your appointment is tomorrow at 2pm',
  scheduledFor: '2024-01-16T09:00:00Z',
});

Viewing Messages

Via Dashboard

1. Navigate to SMS → Messages in the sidebar
2. Browse all sent SMS messages with filters for status and date range
3. Click on any message to view its full content, delivery status, and provider info

Via API

# List SMS messages
curl "https://api.zyphr.dev/v1/sms?page=1&per_page=25" \
  -H "X-API-Key: zy_live_your_key"

# Get a specific SMS
curl https://api.zyphr.dev/v1/sms/SMS_ID \
  -H "X-API-Key: zy_live_your_key"

Provider Setup

You can configure SMS providers through the Dashboard or the API.

Supported Providers

Provider	Credentials Required
Twilio	Account SID, Auth Token, From Number
Vonage	API Key, API Secret, From Number
Plivo	Auth ID, Auth Token, From Number
MessageBird	API Key, Originator
Telnyx	API Key, From Number
Sinch	Service Plan ID, API Token, From Number, Region (optional)

Via Dashboard

1. Navigate to SMS → Providers in the sidebar
2. Click Add Provider
3. Select your SMS provider from the dropdown
4. Enter the required credentials for that provider
5. Set a priority (lower number = higher priority, tried first)
6. Optionally mark as the default provider

From the Providers page you can also edit, delete, and reorder providers.

Via API

# Set SMS provider config
curl -X POST https://api.zyphr.dev/v1/sms/config \
  -H "X-API-Key: zy_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "twilio",
    "account_sid": "YOUR_ACCOUNT_SID",
    "auth_token": "YOUR_AUTH_TOKEN",
    "from_number": "+14155551234"
  }'

# Get current SMS config
curl https://api.zyphr.dev/v1/sms/config \
  -H "X-API-Key: zy_live_your_key"

# Verify SMS config credentials
curl -X POST https://api.zyphr.dev/v1/sms/config/verify \
  -H "X-API-Key: zy_live_your_key"

# Delete SMS config
curl -X DELETE https://api.zyphr.dev/v1/sms/config \
  -H "X-API-Key: zy_live_your_key"

Multi-Provider Fallback

When multiple providers are configured, Zyphr tries them in priority order. If the primary provider fails, the system automatically falls back to the next available provider. Each provider has independent health tracking with a circuit breaker:

• Healthy — Normal operation
• Degraded — Experiencing intermittent failures
• Circuit Open — Temporarily disabled after repeated failures (auto-recovers after 5 minutes)

Provider Health

Monitor provider health from the Dashboard (SMS → Providers) or query the API. You can:

• View real-time health status for each provider
• See failure counts and history
• Reset circuit breakers manually if a provider has recovered
• Reorder provider priority

SMS Status

Status	Description
queued	SMS accepted and queued
sending	Being sent to provider
sent	Accepted by carrier network
delivered	Delivered to handset
undelivered	Failed to reach handset
failed	Permanent failure

Webhooks

Receive SMS delivery events:

{
  "event": "sms.delivered",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "message_id": "sms_abc123",
    "to": "+14155551234",
    "status": "delivered",
    "segments": 1
  }
}

Error Handling

Error Code	Description	Solution
sms_not_configured	No SMS provider configured	Add a provider in SMS → Providers
invalid_phone_number	Invalid phone format	Use E.164 format
undeliverable	Number cannot receive SMS	Check number is valid
blacklisted	Number opted out	Respect opt-out

Compliance

Opt-Out Handling

Zyphr automatically handles STOP/UNSUBSCRIBE replies:

1. User replies STOP to your number
2. The SMS provider notifies Zyphr
3. Number added to suppression list
4. Future sends to that number are blocked

Consent Best Practices

• Always get explicit consent before sending SMS
• Include opt-out instructions in marketing messages
• Keep records of consent
• Honor opt-out requests immediately

Pricing

SMS pricing varies by country and provider. Zyphr passes through your provider's pricing with no markup. Check your provider's dashboard for current rates.