SMS API
Send SMS messages to any phone number in the world. Canary handles carrier routing, 10DLC compliance, and delivery optimization automatically.
Global Reach
Local numbers in 140+ countries with automatic carrier selection.
10DLC Compliant
Full A2P 10DLC registration and compliance handled for you.
Fast Delivery
Average delivery time under 500ms with 99.9% deliverability.
Quick Start
Send your first SMS message in seconds. All you need is your API key and a destination phone number.
curl -X POST https://api.canarymsg.dev/v1/sms \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '
{
"to": "+15551234567",
"message": "Hello from Canary! Your verification code is 123456."
}
'Response
{
"id": "msg_abc123xyz",
"to": "+15551234567",
"from": "+15559876543",
"message": "Hello from Canary! Your verification code is 123456.",
"status": "queued",
"segments": 1,
"created_at": "2024-01-01T12:00:00Z"
}Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
to | string | Recipient phone number in E.164 format | |
message | string | The message content (max 1600 characters) | |
from | string | Optional | Sender phone number (defaults to your primary number) |
webhook_url | string | Optional | URL to receive delivery status updates |
scheduled_at | string | Optional | ISO 8601 timestamp to schedule the message |
metadata | object | Optional | Custom key-value pairs for your reference |
Bulk SMS
Send messages to multiple recipients in a single API call. Each message is processed independently and will receive its own delivery status.
{
"messages": [
{
"to": "+15551234567",
"message": "Hello Alice! Your order is ready."
},
{
"to": "+15559876543",
"message": "Hello Bob! Your order is ready."
},
{
"to": "+15551112222",
"message": "Hello Carol! Your order is ready."
}
]
}Message Status
Track the delivery status of your messages. You can poll the API or configure webhooks to receive real-time updates.
curl https://api.canarymsg.dev/v1/sms/msg_abc123xyz \
-H "Authorization: Bearer YOUR_API_KEY"Status Values
| Status | Description |
|---|---|
| queued | Message is queued for delivery |
| sent | Message was sent to the carrier |
| delivered | Message was delivered to the recipient |
| failed | Message delivery failed |
| undelivered | Carrier could not deliver the message |
Phone Numbers
Manage your phone numbers programmatically. Purchase new numbers, configure settings, and handle incoming messages.
List Phone Numbers
{
"data": [
{
"id": "pn_abc123",
"phone_number": "+15559876543",
"country": "US",
"type": "local",
"capabilities": ["sms", "mms", "voice"],
"10dlc_status": "verified"
}
],
"has_more": false
}Purchase a Number
{
"country": "US",
"type": "local",
"area_code": "415",
"capabilities": ["sms", "voice"]
}10DLC Compliance
What is 10DLC?
10DLC (10-Digit Long Code) is a system for businesses to send Application-to-Person (A2P) messages using standard 10-digit phone numbers. US carriers require 10DLC registration for business messaging.
Canary handles 10DLC registration automatically. When you create an account and add your business information, we register your brand and campaigns with The Campaign Registry (TCR).
Registration Status
{
"brand": {
"id": "brand_xyz",
"status": "verified",
"trust_score": 85
},
"campaigns": [
{
"id": "campaign_abc",
"use_case": "2fa",
"status": "active",
"throughput": 3000
}
]
}SDK Examples
Node.js
import Canary from '@canary/node';
const canary = new Canary('YOUR_API_KEY');
const message = await canary.sms.send({
to: '+15551234567',
message: 'Hello from Canary!',
});
console.log('Message sent:', message.id);Python
from canary import Canary
canary = Canary("YOUR_API_KEY")
message = canary.sms.send(
to="+15551234567",
message="Hello from Canary!"
)
print(f"Message sent: {message.id}")