Send SMS

Send an SMS message through the Vendel API.

POST /api/sms/send

Request

Headers

Header Value
X-API-Key YOUR_API_KEY
Content-Type application/json

Alternatively, you can use JWT authentication with Authorization: Bearer YOUR_JWT_TOKEN.

Body

Field Type Required Description
recipients string[] Yes Array of phone numbers in E.164 format (e.g., ["+1234567890"])
body string Yes Message content (max 1600 characters)
device_id string No Specific device to use. If omitted, auto-selected via round-robin.

Example

curl -X POST https://your-server.com/api/sms/send \
  -H "X-API-Key: vk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "recipients": ["+1234567890"],
    "body": "Your verification code is 123456"
  }'

Response

Success (200 OK)

{
  "message_ids": ["a1b2c3d4e5f6g7h"],
  "recipients_count": 1,
  "status": "accepted"
}

For multiple recipients, a batch_id field is also included:

{
  "batch_id": "x9y8z7w6v5u4t3s",
  "message_ids": ["a1b2c3d4e5f", "g7h8i9j0k1l"],
  "recipients_count": 2,
  "status": "accepted"
}

Message statuses

Status Description
pending Message created, no device assigned yet
assigned Device assigned, wake-up signal sent to device
sending Device is sending the message
sent Message was sent successfully
delivered Message was delivered (if delivery reports enabled)
failed Message failed to send

Errors

// 400 Bad Request - Invalid phone number
{
  "error": "invalid_phone_number",
  "message": "Phone number must be in E.164 format"
}

// 401 Unauthorized - Invalid API key
{
  "error": "unauthorized",
  "message": "Authentication required"
}

// 402 Payment Required - Quota exceeded
{
  "error": "quota_exceeded",
  "message": "Monthly message quota exceeded"
}

// 503 Service Unavailable - No devices available
{
  "error": "no_devices",
  "message": "No devices available to send messages"
}

Code examples

Python

import requests

response = requests.post(
    "https://your-server.com/api/sms/send",
    headers={
        "X-API-Key": "vk_your_api_key",
        "Content-Type": "application/json"
    },
    json={
        "recipients": ["+1234567890"],
        "body": "Hello from Python!"
    }
)

print(response.json())

JavaScript

const response = await fetch("https://your-server.com/api/sms/send", {
  method: "POST",
  headers: {
    "X-API-Key": "vk_your_api_key",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    recipients: ["+1234567890"],
    body: "Hello from JavaScript!"
  })
});

const data = await response.json();
console.log(data);

Related