Skip to main content
Send SMS messages to multiple recipients in a single API call. This is more efficient than making individual requests for each recipient.

​
Request Body

​
to
string[]
required
An array of recipient phone numbers in E.164 format. Maximum 100 recipients per request.
["+14155551234", "+14155555678", "+447700900123"]
​
body
string
required
The SMS message content. Maximum 1600 characters. The same message is sent to all recipients.
​
from
string
Optional alphanumeric sender ID (1-11 characters). Not all countries support custom sender IDs.
​
metadata
object
Custom key-value pairs attached to all messages.
​
tags
string[]
Tags for categorization and analytics.

​
Limits

LimitValue
Max recipients per request100
Max message length1600 characters
Rate limitPlan-dependent
For sending to more than 100 recipients, make multiple API calls in batches.

​
Example

curl -X POST https://www.unosend.co/api/v1/sms \
  -H "Authorization: Bearer un_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": [
      "+14155551234",
      "+14155555678",
      "+447700900123"
    ],
    "body": "Flash sale! 50% off all items. Shop now at example.com"
  }'

​
Response

Returns a result for each recipient, indicating success or failure. 
{
  "data": [
    {
      "id": "sms_abc123",
      "to": "+14155551234",
      "status": "sent",
      "message_id": "acs_xyz789",
      "segments": 1
    },
    {
      "id": "sms_def456",
      "to": "+14155555678",
      "status": "sent",
      "message_id": "acs_uvw012",
      "segments": 1
    },
    {
      "id": "sms_ghi789",
      "to": "+447700900123",
      "status": "sent",
      "message_id": "acs_rst345",
      "segments": 1
    }
  ]
}

​
Partial Failures

When sending to multiple recipients, some messages may fail while others succeed. Always check the status field for each result: 
{
  "data": [
    {
      "id": "sms_abc123",
      "to": "+14155551234",
      "status": "sent",
      "segments": 1
    },
    {
      "id": "sms_def456",
      "to": "+1invalid",
      "status": "failed",
      "error": "Invalid phone number format"
    }
  ]
}

​
Cost Calculation

Batch SMS is charged per message segment:
  • Cost: $0.01 per segment
  • Total cost: (number of recipients) × (segments per message) × $0.01
Example: Sending a 200-character GSM message to 50 recipients:
  • Segments: 2 (200 chars ÷ 153 chars/segment for multipart)
  • Total segments: 50 × 2 = 100 segments
  • Total cost: 100 × 0.01=∗∗0.01 = **1.00**

​
Best Practices

  1. Validate phone numbers before sending to reduce failed deliveries
  2. Use E.164 format (+1234567890) for all phone numbers
  3. Batch requests to 100 recipients maximum per call
  4. Handle partial failures by checking each result’s status
  5. Respect rate limits based on your plan

​
Sending to Large Lists

For sending to thousands of recipients: 
async function sendBulkSms(phoneNumbers, message) {
  const batchSize = 100;
  const results = [];
  
  for (let i = 0; i < phoneNumbers.length; i += batchSize) {
    const batch = phoneNumbers.slice(i, i + batchSize);
    
    const response = await fetch('https://www.unosend.co/api/v1/sms', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer un_your_api_key',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        to: batch,
        body: message,
      }),
    });
    
    const data = await response.json();
    results.push(...data.data);
    
    // Optional: Add delay between batches to respect rate limits
    await new Promise(resolve => setTimeout(resolve, 1000));
  }
  
  return results;
}

// Usage
const phones = ['+14155551234', '+14155555678', /* ... thousands more */];
const results = await sendBulkSms(phones, 'Your promotional message here');