はじめに

Bulk SMS API リファレンス

BulkSMSAPIは開発者向けの一括SMS APIです: REST経由で1つのテキストまたは1リクエストあたり最大10,000件の番号を227ヶ国に送信し、署名付きウェブフックで各メッセージを追跡し、プリペイド残高からメッセージごとに支払います。このリファレンスでは、APIのすべてのエンドポイント、フィールド、イベント、エラーを網羅しています。各ページはMarkdown形式でも利用可能で、アドレスに.mdを追加してください。

ベースURLと形式

すべてのリクエストはHTTPS経由でhttps://bulksmsapi.cc/v1に送信されます。ボディはJSON形式(Content-Type: application/json、UTF-8エンコード)で、すべての応答(エラーを含む)もJSONです。時刻はUTCのISO 8601形式です。金額は5桁の小数を持つUSドル文字列("0.00507")で、1セント未満の価格も正確に表現されます。

エンドポイント

メソッドとパス機能Key
POST /v1/messages1つの番号に1つのテキストを送信Yes
POST /v1/batches最大10,000件の番号に、1つのテキストまたは番号ごとに個別のテキストを送信Yes
GET /v1/messages/{id}ステータスと価格を含む1つのメッセージYes
GET /v1/messagesメッセージ(新しい順)、バッチまたはステータスでフィルタリングYes
GET /v1/batches/{id}ステータスごとの件数を含む1つのバッチYes
GET /v1/batchesバッチ(新しい順)Yes
POST /v1/batches/{id}/cancel予約済みバッチのキャンセル(全額返金)Yes
POST /v1/estimates送信せずにリクエストの料金を計算Yes
GET /v1/balanceUSD残高Yes
GET /v1/pricing各国のセグメント単価No
GET /v1/pricing/{country}1か国分の料金(ISOコード指定)No

最初のリクエスト

コンソールでAPIキーを作成・エクスポートし、メッセージを送信します。202応答とメッセージオブジェクトが返されます:コストは残高から差し引かれ、メッセージはキューに入ります。

curl https://bulksmsapi.cc/v1/messages \
  -H "Authorization: Bearer $BULKSMSAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155550123",
    "text": "Your Northwind code is 482913. It expires in 10 minutes.",
    "reference": "login-7781"
  }'
202 AcceptedJSON
{
  "id": "msg_8F3K2Q9TZ1MX",
  "object": "message",
  "batch_id": "bat_4M7Q1X0PK2RS",
  "to": "+14155550123",
  "country": "US",
  "text": "Your Northwind code is 482913. It expires in 10 minutes.",
  "segments": 1,
  "price": "0.00507",
  "currency": "USD",
  "status": "queued",
  "error": null,
  "reference": "login-7781",
  "created_at": "2026-11-07T09:30:12.418Z",
  "sent_at": null,
  "done_at": null
}

メッセージの流れ

受理されたメッセージはqueued(またはsend_at指定時はscheduled)状態になります。キューは2秒ごとにネットワークへ渡し(アカウント毎分1,200件上限)、sent状態に。最終状態はdeliveredかfailedで、失敗時は即時返金されます。各最終状態で署名付きイベントがwebhookへ通知されます。

制限の概要

制限値
APIリクエストあたりの送信先数10,000
コンソールキャンペーンあたりの送信先数50,000
キーあたり毎分リクエスト数600
アカウントあたり毎分ネットワーク送信件数1,200
最大文字数10セグメント(GSM-7で1,530文字、UCS-2で670文字)
予約可能期間2分から45日前
イベントあたりのwebhook試行回数10
Idempotency-Keyの保持期間24時間
アカウントあたりのAPIキー数10

機械可読ファイル

Bulk SMS API リファレンス | BulkSMSAPI ドキュメント