• 228 направлений
  • Без KYC — всегда
  • Bitcoin, Monero, USDT и ещё 4 валюты

API2 минуты чтения

Пакетная отправка: как работают частичные отклонения

Один неверный номер не должен срывать пакет из тысячи сообщений. Как проверяется каждое сообщение, что содержит ответ и как обрабатывать отклонения.

SMSMeteor — Команда APIОпубликовано 21 сентября 2026, обновлено

Реальные списки контактов никогда не бывают чистыми. В пакете из тысячи номеров почти всегда найдётся опечатка, стационарный номер или направление, на которое никто не может проложить маршрут. Метод пакетной отправки по принципу «всё или ничего» превращает каждый такой случай в неудачный запрос и цикл повторных попыток на стороне клиента. Метод пакетной отправки SMSMeteor работает иначе: он принимает то, что может отправить, и по каждому элементу сообщает, что отклонил и почему.

Контракт метода

POST /v1/messages/batch принимает до 1000 сообщений в одном запросе API; у каждого сообщения свои to и text и необязательные from и reference. Поля верхнего уровня, такие как from, campaign, send_at, window и pace, применяются ко всем сообщениям, в которых они не переопределены. Далее проверка выполняется на двух уровнях:

  • Если некорректен сам запрос — например, JSON недействителен или элементов больше, чем разрешено, — весь запрос отклоняется с ошибкой и ничего не ставится в очередь.
  • Если запрос корректен, но некоторые сообщения — нет, эти сообщения возвращаются как отклонённые вместе с ошибкой, а все корректные сообщения ставятся в очередь.

Что содержит ответ

В ответе указано, сколько сообщений принято и сколько отклонено, общая стоимость принятых и список сообщений с их статусами:

JSON
{
  "batch_id": "bat_3Hq9Zr",
  "accepted": 2, "rejected": 1,
  "total_price": "0.0326", "currency": "USD",
  "messages": [
    { "id": "msg_9Kd2fQ", "to": "+14155550142", "status": "queued" },
    { "id": "msg_9Kd2fR", "to": "+447400123456", "status": "queued" },
    { "to": "+44 74", "status": "rejected", "error": "invalid_number" }
  ]
}

Точный состав полей описан в справочнике API и в файле OpenAPI.

Почему элементы отклоняются

  • Номер не является допустимым номером E.164 для своей страны.
  • Мы не доставляем сообщения в это направление.
  • Текст длиннее допустимого (6 частей на сообщение).
  • Содержание отклонено фильтрами, которые обеспечивают соблюдение правил допустимого использования.

Отклонённые сообщения никогда не оплачиваются и никогда не передаются оператору связи. В отчёте они перечислены вместе с кампанией, поэтому можно исправить источник проблемы, а не её симптом.

Повторные запросы без двойной отправки

Соединение между вашим сервером и нашим может обрываться. Если пакетный запрос завершился по тайм-ауту, вы не можете знать, был ли он обработан. Отправляйте каждый пакет с заголовком Idempotency-Key: повторный запрос с тем же ключом вернёт исходный результат, а не поставит сообщения в очередь второй раз. Используйте ключ, который обозначает бизнес-операцию, например кампанию и номер части, а не случайное значение, создаваемое при каждой попытке.

Пропускная способность

API допускает 50 запросов в секунду на ключ, а пакет считается одним запросом. Поэтому быстрее всего загружать большие списки пакетами до 1000 сообщений в одном запросе API, а темп отправки лучше задавать параметром pace — поминутно или с распределением на несколько часов, — чем паузами в собственном коде.

И всё же очищайте данные заранее

Частичное отклонение — это страховочная сетка, а не инструмент очистки списков. Перед отправкой приводите номера к формату E.164, удаляйте дубликаты и исключайте номера, которые в прошлых кампаниях оказались неизвестными. Импорт в панели делает это для файлов и сообщает, что было удалено; каждый шаг описан в руководстве по подготовке списка контактов.

Памятка по интеграции пакетной отправки

  1. Разбивайте списки на пакеты — не более 1000 сообщений в одном запросе API.
  2. Отправляйте каждую часть с неизменным Idempotency-Key.
  3. Сохраняйте полученные идентификаторы сообщений вместе со своими значениями reference.
  4. Записывайте отклонённые элементы в журнал вместе с ошибкой и исправляйте исходные данные.
  5. Используйте pace и window вместо управления временем на стороне клиента.
Попробуйте возможности из этой статьи.Для регистрации достаточно адреса электронной почты. Тарифы опубликованы, оплата принимается в криптовалюте.
Начать отправку