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.
group_ids string[] No Contact group IDs. Members are added to recipients (deduplicated).

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"],
    "group_ids": ["GROUP_ID_1", "GROUP_ID_2"],
    "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);

Send SMS with template

POST /api/sms/send-template

Send an SMS using a saved template with variable interpolation. Reserved variables ({{name}}, {{phone}}) are automatically filled from your contacts. Custom variables must be provided in the variables field.

Body

Field Type Required Description
recipients string[] Yes Array of phone numbers in E.164 format
template_id string Yes ID of the template to use
variables object No Key-value map of custom variable values (e.g., {"code": "1234"})
device_id string No Specific device to use. If omitted, auto-selected via round-robin.
group_ids string[] No Contact group IDs. Members are added to recipients (deduplicated).

Example

curl -X POST https://your-server.com/api/sms/send-template \
  -H "X-API-Key: vk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "recipients": ["+1234567890"],
    "template_id": "TEMPLATE_RECORD_ID",
    "variables": {
      "code": "123456",
      "minutes": "10"
    }
  }'

The response format is identical to /api/sms/send. Each recipient receives a personalized message — if +1234567890 is a saved contact named "Alice", a template like Hi {{name}}, your code is {{code}} becomes Hi Alice, your code is 123456.

Errors

// 400 Bad Request - Template not found
{
  "message": "Template not found."
}

// 400 Bad Request - Missing variable
{
  "message": "Missing variable: code."
}

// 400 Bad Request - Template ownership
{
  "message": "Template does not belong to user."
}

Related