Gönderim

POST /v1/batches ile toplu SMS gönder

POST/v1/batches

Tek bir istekle 10.000 numaraya kadar gönderin. Tüm maliyet bakiyeden bir seferde alınır.

İstek gövdesi

  • toarray of stringsisteğe bağlı

    Paylaşılan bir metin için numaralar. Ya to ile text, ya da messages kullanın.

  • textstringisteğe bağlı

    Paylaşılan metin, to ile kullanıldığında zorunlu.

  • messagesarray of objectsisteğe bağlı

    Kişiselleştirilmiş metinler için her alıcıya bir {to, text}.

  • namestringisteğe bağlı

    Konsol için bir etiket, en fazla 100 karakter.

  • referencestringisteğe bağlı

    Kendi id'niz, en fazla 100 karakter, parti ve her mesajda döndürülür.

  • send_atstringisteğe bağlı

    ISO 8601 zamanı, 2 dakika ile 45 gün arasında.

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

Ayrılan numaralar

Her numara ayrı ayrı temizlenir ve fiyatlandırılır. Gönderilemeyen numaralar partiden çıkarılır, ücretlendirilmez ve set_aside içinde bir nedenle listelenir:

reasonAnlam
invalid_numberTemizleme sonrası + ve 7-15 basamak olarak okunamıyor.
duplicateAynı numara istek içinde daha önce geçti.
unsupported_countryNumara fiyatlandırılmış bir ülkeye ait değil.
too_longKişiselleştirilmiş metni 10'dan fazla segment gerektiriyor.
empty_textKişiselleştirilmiş metni boş.
suppressedNumara gönderme yapılmayacaklar listesinde.

Hiç numara kalmazsa, istek ilk nedenin koduyla (örneğin invalid_number) başarısız olur ve hiçbir şey ücretlendirilmez.

Numara başına kişiselleştirilmiş metin

Her alıcıya kendi metnini vermek için messages kullanın: isimler, zamanlar, miktarlar. Her metin kendi başına sayılır ve fiyatlandırılır, böylece bir parti tek segmentli ve iki segmentli mesajları karıştırabilir.

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

Planlama

send_at ile parti ve mesajları scheduled durumunda bekler ve o dakika kuyruğa alınır. Maliyet istek kabul edildiğinde alınır, bu yüzden zamanlanmış bir partinin her zaman fonları vardır. Zamanlanmış bir parti başlayana kadar iptal edilebilir.

POST/v1/batches/{id}/cancel

Zamanlanmış bir partiyi iptal eder: her mesaj iptal edilir ve tam maliyet tek bir iade satırı olarak bakiyeye döner. Başlamış bir parti 409 not_cancelable ile yanıt verir.

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

Partileri getir ve listele

GET/v1/batches/{id}

Her durum için canlı sayımlara sahip toplu işlem. İlerleme için sorgulayın veya webhook'ları kullanın.

GET/v1/batches

Hesabın toplu işlemleri, en yeniden eskiye doğru, limit (1 ile 100 arası) ve starting_after (bir bat_ id) ile.

Toplu işlem alanları

  • idstring

    bat_ ardından 12 karakter.

  • statusstring

    zamanlanmış, sıraya alınmış, gönderiliyor, tamamlandı veya iptal edildi.

  • sourcestring

    api veya konsol.

  • encodingstring

    GSM-7 veya herhangi bir metin Unicode gerektirdiğinde UCS-2.

  • recipientsinteger

    Toplu işleme kabul edilen numaralar.

  • max_segmentsinteger

    Metinler arasındaki en büyük segment sayısı.

  • coststring

    Bakiyeden alınan toplam, USD.

  • refundedstring

    Şu ana kadar başarısız veya iptal edilen mesajlar için iade edilen toplam.

  • countsobject

    Duruma göre mesajlar: zamanlanmış, sıraya alınmış, gönderildi, teslim edildi, başarısız oldu, iptal edildi.

  • send_atstring or null

    Zamanlanmış zaman, varsa.

  • completed_atstring or null

    Son mesajın nihai duruma ulaştığı zaman.

Daha büyük listeler

10.000'den fazla numara içeren listeleri, her birinin kendi Idempotency-Key'i ile (örneğin liste kimliği ve parça numarası) birkaç isteğe bölün. Mesajlar dakikada hesap başına 1.200'e kadar sırayla ağa teslim edilir, bu nedenle 50.000 numaralı bir kampanya bir saatten kısa sürede yola çıkar. Konsol, her kampanya için 50.000 numarayı bir yapıştırma veya CSV dosyasından alır.

POST /v1/batches ile toplu SMS gönder | BulkSMSAPI Docs