發送

使用 POST /v1/messages 發送簡訊

POST/v1/messages

傳送一則簡訊至一個號碼。費用會在請求被接受時從餘額中扣除。

請求主體

  • tostring必填

    國際格式的號碼,例如 +14155550123。空格、破折號、括號和 00 前綴會被清除。

  • textstring必填

    訊息內容。最多 10 個分段;請參閱文字與分段。

  • referencestring選填

    您自訂的 ID,最多 100 個字元。它會出現在訊息物件和每個 webhook 中。

  • send_atstring選填

    ISO 8601 格式的傳送時間,可設定為 2 分鐘到 45 天後。若未設定,訊息會立即排入佇列。

加入 Idempotency-Key 標頭以確保重試安全:請參閱冪等性。

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
}

訊息物件

欄位

  • idstring

    訊息 ID,msg_ 後接 12 個字元。

  • objectstring

    始終為 message。

  • batch_idstring

    訊息所屬的批次(單一訊息也會獲得一個批次)。

  • tostring

    清理後的 E.164 格式號碼。

  • countrystring

    號碼計價所屬國家的 ISO 3166 代碼。

  • textstring

    已傳送的文字,合併欄位已填入。

  • segmentsinteger

    文字使用的 SMS 分段數量。

  • pricestring

    此訊息的價格,以美元計,精確到小數點後五位(每分段價格乘以分段數)。

  • currencystring

    始終為美元。

  • statusstring

    scheduled(已排程)、queued(已排入佇列)、sent(已傳送)、delivered(已送達)、failed(失敗)或 canceled(已取消)。

  • errorobject or null

    對於失敗或取消的訊息:錯誤代碼和訊息。

  • referencestring or null

    您自訂的參考資料,來自請求。

  • created_atstring

    請求被接受的時間(ISO 8601,UTC)。

  • sent_atstring or null

    訊息被傳遞給網路的時間。

  • done_atstring or null

    最終狀態(已送達、失敗或已取消)被設定的時間。

取得訊息

GET/v1/messages/{id}

根據 msg_ id 取得一則訊息。其他帳戶的訊息會回傳 404。

curl https://bulksmsapi.cc/v1/messages/msg_8F3K2Q9TZ1MX \
  -H "Authorization: Bearer $BULKSMSAPI_KEY"

列出訊息

GET/v1/messages

帳戶的訊息,最新優先。

查詢參數

  • batch_idstring選填

    僅此 bat_ 批次的訊息。

  • statusstring選填

    scheduled(已排程)、queued(已排入佇列)、sent(已傳送)、delivered(已送達)、failed(失敗)或 canceled(已取消)。

  • limitinteger選填

    1 到 100,預設為 20。

  • starting_afterstring選填

    msg_ id:頁面從此之後開始。使用前一頁的最後一個 id。

curl "https://bulksmsapi.cc/v1/messages?status=failed&limit=50" \
  -H "Authorization: Bearer $BULKSMSAPI_KEY"
200 OKJSON
{
  "object": "list",
  "data": [ { "id": "msg_8F3K2Q9TZ1MX", "object": "message", "status": "failed", "...": "..." } ],
  "has_more": false
}
使用 POST /v1/messages 發送簡訊 | BulkSMSAPI 文件