Send SMS

POST /v1/sms/send

Dispatches a standard text message (SMS) to a mobile phone number anywhere in the world. Our global routing engine will automatically select the optimum tier-1 telecom carrier for the destination country to maximize deliverability and minimize latency.

Authentication

All requests to this endpoint must include your API key in the Authorization header as a Bearer token.

Header	Type	Required	Description
Authorization	string	Yes	Bearer sk_live_YOUR_API_KEY
Idempotency-Key	string	No	A unique UUIDv4 to prevent duplicate deliveries on network retries.

Request Body

Send an application/json payload with the following parameters:

Parameter	Type	Required	Description
to	string	Yes	The destination phone number in E.164 format (e.g., +14155552671). Max 20 characters.
content	string	Yes	The text content of the SMS. Maximum length is 1600 characters.
sender_id	string	No	Optional custom alphanumeric Sender ID (up to 11 characters) to display instead of the default. Note: Requires pre-registration in certain countries.

Example Request

cURL

curl -X POST https://sendapi.co/v1/sms/send \
  -H "Authorization: Bearer sk_live_123456789" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+447700900000",
    "content": "Your package has been dispatched. Track it at https://example.com",
    "sender_id": "AcmeCorp"
  }'

Node.js

import { SendAPI } from '@sendapi/node';

const client = new SendAPI('sk_live_123456789');

const response = await client.sms.send({
  to: '+447700900000',
  content: 'Your package has been dispatched. Track it at https://example.com',
  sender_id: 'AcmeCorp'
});

console.log(response.data.id);

Python

response = client.sms.send(
    to="+447700900000",
    content="Your package has been dispatched. Track it at https://example.com",
    sender_id="AcmeCorp"
)

Response

Returns a message object indicating that the SMS has been successfully submitted to the carrier network. The cost is deducted from your SMS credit balance immediately.

{
  "success": true,
  "data": {
    "id": 32,
    "to": "+447700900000",
    "segments": 1,
    "cost": "$0.0250",
    "region": "United Kingdom",
    "status": "queued",
    "provider": "telnyx",
    "external_id": "40319d98-8ece-401e-9add-94b696939751",
    "sms_credit_balance": "$1.4000",
    "created_at": "2026-04-16T23:09:49.000000Z"
  },
  "meta": {
    "request_id": "44b5b9cb-6139-47f8-bbc0-e496b0c72ac6",
    "timestamp": "2026-04-16T23:09:49.052104Z"
  }
}

Response Fields

Field	Description
id	Unique SendAPI message ID.
to	Destination phone number.
segments	Number of SMS segments (1 segment = 160 characters for GSM-7).
cost	Cost charged for this message from your SMS credit balance.
region	Detected destination country based on the phone number.
status	Current message status (queued, sent, delivered, failed).
provider	The underlying carrier used for delivery.
external_id	Carrier-assigned message ID for tracking.
sms_credit_balance	Your remaining SMS credit balance after this message.

Rate Limits

Standard API rate limits apply (see Rate Limits). For high-volume sends, use the Bulk SMS endpoint.

Sender ID Behaviour

If you pass a sender_id that is pending approval, SendAPI will silently fall back to the default sender and include a sender_id_note and sender_id_fallback field in the response so you know. If the sender ID is rejected, the request returns 422. To register a new sender ID, use the /v1/sms/sender-ids endpoints.