送信

一括SMSを送信するには POST /v1/batches

POST/v1/batches

1リクエストで最大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"
    ]
  }'
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": []
}

除外された番号

各番号は個別にクリーニングと料金計算されます。送信不可の番号はバッチから除外され、課金されず、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状態で待機し、指定時刻にキューに移動します。コストはリクエスト受理時に引き落とされるため、スケジュール済みバッチには常に資金が確保されます。開始前までキャンセル可能です。

POST/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"

バッチの取得と一覧表示

GET/v1/batches/{id}

ステータス別のリアルタイムカウント付きバッチ情報。進捗確認用にポーリングするか、Webhookを使用してください。

GET/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件まで対応

一括SMSを送信するには POST /v1/batches | BulkSMSAPI ドキュメント