送信
一括SMSを送信するには POST /v1/batches
/v1/batches1リクエストで最大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"
]
}'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": []
}除外された番号
各番号は個別にクリーニングと料金計算されます。送信不可の番号はバッチから除外され、課金されず、set_asideに理由と共にリストされます:
| reason | 意味 |
|---|---|
| invalid_number | クリーニング後、+と7~15桁の数字として認識できない。 |
| duplicate | リクエスト内で同じ番号が既に出現している。 |
| unsupported_country | 該当番号の国・地域に料金設定がありません。 |
| too_long | 個別テキストが10セグメントを超える。 |
| empty_text | 個別テキストが空です。 |
| suppressed | 送信除外リストに登録されている番号です。 |
有効な番号が1件も残らない場合、最初の理由コード(例: invalid_number)でリクエストが失敗し、課金されません。
番号ごとの個別テキスト
messagesを使用して受信者ごとに個別テキスト(名前、時間、金額など)を設定可能。各テキストは個別にカウント・課金されるため、1セグメントと2セグメントのメッセージを混在させられます。
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状態で待機し、指定時刻にキューに移動します。コストはリクエスト受理時に引き落とされるため、スケジュール済みバッチには常に資金が確保されます。開始前までキャンセル可能です。
/v1/batches/{id}/cancelスケジュール済みバッチをキャンセル:全メッセージがcanceled状態になり、全額が1行の返金として残高に戻ります。開始済みバッチは409 not_cancelableで応答します。
curl -X POST https://bulksmsapi.cc/v1/batches/bat_6TQ2W8M1ZK4N/cancel \
-H "Authorization: Bearer $BULKSMSAPI_KEY"バッチの取得と一覧表示
/v1/batches/{id}ステータス別のリアルタイムカウント付きバッチ情報。進捗確認用にポーリングするか、Webhookを使用してください。
/v1/batchesアカウントのバッチ一覧(新しい順)、limit(1~100)とstarting_after(bat_ ID)でページネーション
バッチフィールド
- idstring
bat_ に続く12文字のID
- statusstring
scheduled(予約済み)、queued(キュー待機中)、sending(送信中)、completed(完了)、canceled(キャンセル済み)
- sourcestring
api(API経由)またはconsole(コンソール経由)
- encodingstring
GSM-7(標準文字)またはUCS-2(Unicode文字を含む場合)
- recipientsinteger
バッチに受け入れられた電話番号数
- max_segmentsinteger
メッセージ中の最大セグメント数
- coststring
残高から引き落とされた合計金額(USD)
- refundedstring
失敗またはキャンセルされたメッセージの返金額(これまでの累計)
- countsobject
ステータス別メッセージ数: scheduled, queued, sent, delivered, failed, canceled
- send_atstring or null
予約送信時刻(設定されている場合)
- completed_atstring or null
最終メッセージが確定ステータスになった時刻
大規模なリスト
10,000件を超えるリストは複数リクエストに分割(各部分に固有のIdempotency-Keyを設定)。メッセージは最大1,200件/分/アカウントで順次送信されるため、50,000件のキャンペーンは1時間未満で処理されます。コンソールでは貼り付けまたはCSVからキャンペーンあたり50,000件まで対応