Отправка

Отправка SMS через POST /v1/batches

POST/v1/batches

Отправка до 10 000 номеров в одном запросе. Вся сумма списывается с баланса сразу.

Тело запроса

  • toarray of stringsнеобязательно

    Номера для общего текста. Используйте либо to с text, либо messages.

  • textstringнеобязательно

    Общий текст, обязателен с to.

  • messagesarray of objectsнеобязательно

    По одному {to, text} на получателя для персональных сообщений.

  • namestringнеобязательно

    Метка для консоли, до 100 символов.

  • referencestringнеобязательно

    Ваш собственный id (до 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"
    ]
  }'
202 AcceptedJSON
{
  "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 и переходят в очередь в указанное время. Средства списываются при принятии запроса, поэтому запланированный пакет всегда обеспечен. Можно отменить до начала отправки.

POST/v1/batches/{id}/cancel

Отмена запланированного пакета: все сообщения отменяются, полная сумма возвращается на баланс одной строкой. Запущенный пакет вернет 409 not_cancelable.

curl -X POST https://bulksmsapi.cc/v1/batches/bat_6TQ2W8M1ZK4N/cancel \
  -H "Authorization: Bearer $BULKSMSAPI_KEY"

Получение и список пакетов

GET/v1/batches/{id}

Пакет с актуальными данными по статусам. Опрашивайте его для отслеживания прогресса или используйте вебхуки.

GET/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-файла.

Отправка SMS через POST /v1/batches | Документация BulkSMSAPI