Gönderim
POST /v1/batches ile toplu SMS gönder
/v1/batchesTek 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"
]
}'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": []
}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:
| reason | Anlam |
|---|---|
| invalid_number | Temizleme sonrası + ve 7-15 basamak olarak okunamıyor. |
| duplicate | Aynı numara istek içinde daha önce geçti. |
| unsupported_country | Numara fiyatlandırılmış bir ülkeye ait değil. |
| too_long | Kişiselleştirilmiş metni 10'dan fazla segment gerektiriyor. |
| empty_text | Kişiselleştirilmiş metni boş. |
| suppressed | Numara 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.
/v1/batches/{id}/cancelZamanlanmış 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
/v1/batches/{id}Her durum için canlı sayımlara sahip toplu işlem. İlerleme için sorgulayın veya webhook'ları kullanın.
/v1/batchesHesabı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.