Wysyłanie

Wyślij masowe SMS-y za pomocą POST /v1/batches

POST/v1/batches

Wyślij do maksymalnie 10 000 numerów w jednym żądaniu. Cały koszt jest pobierany z salda jednocześnie.

Treść żądania

  • toarray of stringsopcjonalne

    Numery dla jednego wspólnego tekstu. Użyj albo to z text, albo messages.

  • textstringopcjonalne

    Wspólny tekst, wymagany z to.

  • messagesarray of objectsopcjonalne

    Jeden {to, text} na odbiorcę, dla osobnych tekstów.

  • namestringopcjonalne

    Etykieta dla konsoli, do 100 znaków.

  • referencestringopcjonalne

    Twoje własne id, do 100 znaków, zwracane w partii i każdej wiadomości.

  • send_atstringopcjonalne

    Czas ISO 8601, od 2 minut do 45 dni w przyszłość.

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": []
}

Numery, które są wykluczone

Każdy numer jest czyszczony i wyceniany osobno. Numery, których nie można wysłać, są pomijane w partii, nie są naliczane i wymienione w set_aside z powodem:

reasonZnaczenie
invalid_numberNieczytelne jako + i 7 do 15 cyfr po czyszczeniu.
duplicateTen sam numer pojawił się wcześniej w żądaniu.
unsupported_countryNumer nie należy do kraju z wyceną.
too_longJego osobny tekst wymaga więcej niż 10 segmentów.
empty_textJego osobny tekst jest pusty.
suppressedNumer znajduje się na Twojej liście nie do wysyłki.

Jeśli nie pozostanie żaden numer, żądanie kończy się niepowodzeniem z kodem pierwszego powodu (na przykład invalid_number) i nic nie jest naliczane.

Osobny tekst na numer

Użyj messages, aby dać każdemu odbiorcy jego własny tekst: imiona, czasy, kwoty. Każdy tekst jest liczony i wyceniany osobno, więc partia może mieszać wiadomości jedno- i dwusegmentowe.

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." }
    ]
  }'

Planowanie

Z send_at partia i jej wiadomości czekają w statusie scheduled i przechodzą do kolejki w tej minucie. Koszt jest pobierany, gdy żądanie zostanie zaakceptowane, więc zaplanowana partia zawsze ma swoje środki. Zaplanowaną partię można anulować, dopóki się nie zacznie.

POST/v1/batches/{id}/cancel

Anuluje zaplanowaną partię: każda wiadomość zostaje anulowana, a pełny koszt wraca do salda jako jedna linia zwrotu. Partia, która się rozpoczęła, odpowiada 409 not_cancelable.

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

Pobierz i wyświetl partie

GET/v1/batches/{id}

Partia z aktualnymi liczbami według statusów. Sprawdzaj jej postęp lub korzystaj z webhooków.

GET/v1/batches

Partie konta, od najnowszych, z limitem (1 do 100) i starting_after (identyfikator bat_).

Pola partii

  • idstring

    bat_ po którym następuje 12 znaków.

  • statusstring

    zaplanowane, w kolejce, wysyłane, zakończone lub anulowane.

  • sourcestring

    api lub konsola.

  • encodingstring

    GSM-7 lub UCS-2, gdy tekst wymaga Unicode.

  • recipientsinteger

    Numery zaakceptowane w partii.

  • max_segmentsinteger

    Największa liczba segmentów wśród tekstów.

  • coststring

    Łączna kwota pobrana z salda, USD.

  • refundedstring

    Łączna kwota zwrócona za nieudane lub anulowane wiadomości.

  • countsobject

    Wiadomości według statusów: zaplanowane, w kolejce, wysłane, dostarczone, nieudane, anulowane.

  • send_atstring or null

    Zaplanowany czas, jeśli dotyczy.

  • completed_atstring or null

    Kiedy ostatnia wiadomość osiągnęła status końcowy.

Większe listy

Podziel listy powyżej 10 000 numerów na kilka żądań, każde z własnym Idempotency-Key (np. ID listy i numer części). Wiadomości są przekazywane do sieci w kolejności, do 1200 na minutę na konto, więc kampania 50 000 numerów jest w drodze w mniej niż godzinę. Konsola przyjmuje 50 000 numerów na kampanię z wklejonej listy lub pliku CSV.

Wyślij masowe SMS-y za pomocą POST /v1/batches | Dokumentacja BulkSMSAPI