Надсилання
Надсилання масових SMS за допомогою POST /v1/batches
/v1/batchesНадіслати до 10 000 номерів в одному запиті. Вся вартість списується з балансу одразу.
Тіло запиту
- toarray of stringsнеобов'язково
Номери для одного спільного тексту. Використовуйте або to з text, або messages.
- textstringнеобов'язково
Спільний текст, обов’язковий з to.
- messagesarray of objectsнеобов'язково
Один {to, text} для кожного отримувача для персональних текстів.
- namestringнеобов'язково
Мітка для консолі, до 100 символів.
- referencestringнеобов'язково
Ваш власний ідентифікатор, до 100 символів, повертається для пакету та кожного повідомлення.
- send_atstringнеобов'язково
Час у форматі ISO 8601, від 2 хвилин до 45 днів вперед.
curl https://bulksmsapi.cc/v1/batches \
-H "Authorization: Bearer $BULKSMSAPI_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: spring-sale-0412" \
-d '{
"name": "Spring sale",
"text": "Spring sale at Northwind: 20% off until Sunday. Opt out: northwind.example/sms",
"to": [
"+14155550123",
"+447400123456",
"+4915123456789"
]
}'const res = await fetch("https://bulksmsapi.cc/v1/batches", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.BULKSMSAPI_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": "spring-sale-0412",
},
body: JSON.stringify({
name: "Spring sale",
text: "Spring sale at Northwind: 20% off until Sunday. Opt out: northwind.example/sms",
to: ["+14155550123", "+447400123456", "+4915123456789"],
}),
});
const batch = await res.json();
console.log(res.status, batch.id, batch.recipients, batch.cost);import json, os, urllib.request
req = urllib.request.Request(
"https://bulksmsapi.cc/v1/batches",
data=json.dumps({
"name": "Spring sale",
"text": "Spring sale at Northwind: 20% off until Sunday. Opt out: northwind.example/sms",
"to": ["+14155550123", "+447400123456", "+4915123456789"],
}).encode(),
headers={
"Authorization": "Bearer " + os.environ["BULKSMSAPI_KEY"],
"Content-Type": "application/json",
"Idempotency-Key": "spring-sale-0412",
"User-Agent": "northwind-app/1.0",
},
method="POST",
)
with urllib.request.urlopen(req) as res:
batch = json.load(res)
print(res.status, batch["id"], batch["recipients"], batch["cost"])<?php
$ch = curl_init("https://bulksmsapi.cc/v1/batches");
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer " . getenv("BULKSMSAPI_KEY"),
"Content-Type: application/json",
"Idempotency-Key: spring-sale-0412",
],
CURLOPT_POSTFIELDS => json_encode([
"name" => "Spring sale",
"text" => "Spring sale at Northwind: 20% off until Sunday. Opt out: northwind.example/sms",
"to" => ["+14155550123", "+447400123456", "+4915123456789"],
]),
]);
$batch = json_decode(curl_exec($ch), true);
echo $batch["id"], " ", $batch["recipients"], " ", $batch["cost"], "\n";package main
import (
"bytes"
"encoding/json"
"fmt"
"net/http"
"os"
)
func main() {
body, _ := json.Marshal(map[string]any{
"name": "Spring sale",
"text": "Spring sale at Northwind: 20% off until Sunday. Opt out: northwind.example/sms",
"to": []string{"+14155550123", "+447400123456", "+4915123456789"},
})
req, _ := http.NewRequest("POST", "https://bulksmsapi.cc/v1/batches", bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+os.Getenv("BULKSMSAPI_KEY"))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Idempotency-Key", "spring-sale-0412")
res, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer res.Body.Close()
var batch map[string]any
json.NewDecoder(res.Body).Decode(&batch)
fmt.Println(res.StatusCode, batch["id"], batch["recipients"], batch["cost"])
}{
"id": "bat_6TQ2W8M1ZK4N",
"object": "batch",
"name": "Spring sale",
"status": "queued",
"source": "api",
"encoding": "GSM-7",
"recipients": 3,
"max_segments": 1,
"cost": "0.02741",
"refunded": "0.00000",
"currency": "USD",
"counts": { "scheduled": 0, "queued": 3, "sent": 0, "delivered": 0, "failed": 0, "canceled": 0 },
"send_at": null,
"reference": null,
"created_at": "2026-11-07T09:31:40.102Z",
"completed_at": null,
"set_aside": []
}Номери, які виключені
Кожен номер очищується та оцінюється окремо. Номери, які не можна надіслати, виключаються з пакету, не списуються та перелічуються в set_aside з причиною:
| reason | Значення |
|---|---|
| invalid_number | Не читається як + та від 7 до 15 цифр після очищення. |
| duplicate | Цей номер вже з’являвся раніше в запиті. |
| unsupported_country | Номер не належить до країни з визначеною ціною. |
| too_long | Персональний текст потребує більше 10 сегментів. |
| empty_text | Персональний текст порожній. |
| suppressed | Номер знаходиться у вашому списку ненадсилання. |
Якщо не залишилося жодного номера, запит завершується з кодом першої причини (наприклад, invalid_number), і нічого не списується.
Персональний текст для кожного номера
Використовуйте messages, щоб надати кожному отримувачу його власний текст: імена, час, суми. Кожен текст підраховується та оцінюється окремо, тому пакет може містити односегментні та двосегментні повідомлення.
curl https://bulksmsapi.cc/v1/batches \
-H "Authorization: Bearer $BULKSMSAPI_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Appointment reminders, 14 May",
"send_at": "2026-05-13T16:00:00Z",
"messages": [
{ "to": "+14155550123", "text": "Hi Ana, your dental check-up is tomorrow at 09:30." },
{ "to": "+14155550178", "text": "Hi Sam, your dental check-up is tomorrow at 11:00." }
]
}'Планування
З send_at пакет та його повідомлення чекають у статусі scheduled та переходять у чергу в зазначену хвилину. Вартість списується під час прийняття запиту, тому запланований пакет завжди має свої кошти. Запланований пакет можна скасувати до його початку.
/v1/batches/{id}/cancelСкасовує запланований пакет: кожне повідомлення стає скасованим, а повна вартість повертається на баланс як один рядок повернення. Пакет, який розпочався, відповідає кодом 409 not_cancelable.
curl -X POST https://bulksmsapi.cc/v1/batches/bat_6TQ2W8M1ZK4N/cancel \
-H "Authorization: Bearer $BULKSMSAPI_KEY"Отримання та перелік пакетів
/v1/batches/{id}Пакет із поточними лічильниками за статусами. Отримуйте оновлення через запити або використовуйте вебхуки.
/v1/batchesПакети облікового запису, від найновіших до найстаріших, з обмеженням (від 1 до 100) та starting_after (bat_ id).
Поля пакету
- idstring
bat_ та 12 символів після нього.
- statusstring
заплановано, в черзі, відправляється, завершено або скасовано.
- sourcestring
api або консоль.
- encodingstring
GSM-7 або UCS-2, якщо текст потребує Unicode.
- recipientsinteger
Номери, прийняті до пакету.
- max_segmentsinteger
Найбільша кількість сегментів серед текстів.
- coststring
Загальна сума, списана з балансу, USD.
- refundedstring
Загальна сума, повернена до балансу за невдалі або скасовані повідомлення.
- countsobject
Повідомлення за статусами: заплановано, в черзі, відправлено, доставлено, невдало, скасовано.
- send_atstring or null
Запланований час, якщо є.
- completed_atstring or null
Коли останнє повідомлення досягло фінального статусу.
Більші списки
Розділіть списки понад 10,000 номерів на кілька запитів, кожен зі своїм Idempotency-Key (наприклад, ідентифікатор списку та номер частини). Повідомлення передаються мережі по порядку зі швидкістю до 1,200 на хвилину на обліковий запис, тому кампанія з 50,000 номерів буде відправлена менш ніж за годину. Консоль приймає до 50,000 номерів на кампанію з вставки або CSV-файлу.