登入 立即開始
Reference / Messages / 傳送簡訊

POST傳送簡訊

POST https://me-sms.com/api/v2/sms/send

傳送 SMS 至指定號碼。支援單號碼或單一 request 最多 2,000,000 號碼的批次傳送。成功時回傳 uuid,可用於至 GET /api/v2/sms/{uuid}/recipients 查詢狀態與送達報告。

– Authentication

如何驗證

請至 Settings → API Keys 頁面建立 API key,並於每次 request 帶入 x-api-key: <key> header。

POST /api/v2/sms/send 端點需具備 sms:send 或 * scope 的 API key,其餘端點僅需任一有效的 API key。

– Body parameters

引數

sender
stringREQUIRED
已核可的 Sender name,長度不超過 11 字元(英文/數字/符號)。可於 Senders 頁面申請新 sender。
content
stringOPTIONAL*
訊息內容,長度不超過 1,000 字元 — 泰文每 70 字元、英文每 160 字元計為 1 則。*content 與 templateId 至少擇一必填。
msisdns
string[]OPTIONAL*
目的號碼,格式 66XXXXXXXXX 或 0XXXXXXXXX;單一 request 最多 2,000,000 個號碼。*msisdns 與 contactGroupId 至少擇一必填。
contactGroupId
integerOPTIONAL
傳送給已建立的 contact group,系統自動展開群組內所有號碼。
templateId
integerOPTIONAL
使用已存的範本取代 content;以 variables 取代範本中如 {{name}} 等變數。
variables
objectOPTIONAL
範本內用以替換的 key/value,例如 {"name":"Toon"}。
scheduledTime
string (ISO 8601)OPTIONAL
預定傳送時間,例如 2026-06-01T10:00:00+07:00。
dryRun
booleanOPTIONAL
設為 true 時只試算費用與則數,不扣點數、不實際傳送。
– Response

回應

200 OK訊息已加入傳送佇列
400 號碼或引數錯誤
401 缺少 / API key 無效
402 點數不足 — 請於 套餐頁面
429 已超出 rate limit — 請降低吞吐
– Delivery status

目的端狀態(per-recipient)

呼叫 GET /api/v2/sms/{uuid}/recipients 可取得每個號碼的狀態。

pending
已進入系統,等待轉送至電信業者。
success
已成功送達 ✓
failed
傳送失敗(號碼關機 / 無訊號)
invalid
號碼無效
blocked
號碼在黑名單中
expired
已超過 retry 時限
timeout
在規定時間內未收到 delivery report

錯誤格式

當 API 回應 4xx/5xx 狀態碼時,回應 body 一律為以下 JSON 結構:

{
  "error": "Insufficient credits",
  "code": "INSUFFICIENT_CREDITS"
}

error 為易讀文字;code 為機器可讀(僅部分端點如 send/retry 才有)。常見 HTTP 狀態碼:

400
引數錯誤
401
缺少 / API key 無效
402
點數不足
403
scope 不足,或非資源擁有者
404
找不到資源
429
已超出 rate limit

POSTPreview cost

POST https://me-sms.com/api/v2/sms/preview-cost

在正式呼叫 /send 之前,計算訊息則數(parts)與將扣除的點數;不會扣除點數、不會實際傳送。

引數 (body)

content
stringREQUIRED
用於試算的內容,長度不超過 2,000 字元。
msisdns
string[]OPTIONAL*
目的號碼 — 擇一使用 msisdns 或 contactGroupId。
contactGroupId
integerOPTIONAL
以 contact group id 取代逐一列出的號碼。
templateId
integerOPTIONAL
以已存的範本取代 content。
variables
objectOPTIONAL
替換範本中的變數值。

POST取消排程的簡訊

POST https://me-sms.com/api/v2/sms/{uuid}/cancel

取消尚未到達傳送時間的排程簡訊;取消後若先前已扣點數會自動退還。

Path

uuid
stringREQUIRED
呼叫 /send 時取得的 UUID。

僅能取消已排程且尚未開始傳送的簡訊(具有 scheduledTime)。若簡訊已開始處理 / 傳送完成 / 已取消,將回傳 HTTP 400 或 409,並帶有 code:NOT_SCHEDULED / ALREADY_CANCELLED / ALREADY_PROCESSING。

GET簡訊列表

GET https://me-sms.com/api/v2/sms

帳號內的簡訊列表,以最新為先。

Query parameters

page
integerOPTIONAL
default 1
limit
integerOPTIONAL
default 20, max 100
status
enumOPTIONAL
sent | failed | pending | scheduled | cancelled
sender
stringOPTIONAL
依 sender 名稱過濾
from / to
ISO 8601OPTIONAL
createdAt 時間區間
search
stringOPTIONAL
於 refNo / content 中搜尋

GET取得單筆簡訊

GET https://me-sms.com/api/v2/sms/{uuid}

單筆 SMS 的詳細資訊,完成傳送後亦包含 drSummary(各狀態的數量)。

GETRecipients (per-recipient status)

GET https://me-sms.com/api/v2/sms/{uuid}/recipients

依收件號碼分別檢視狀態,支援 cursor 分頁,即使百萬規模也能快速翻頁。

Query parameters

limit
integerOPTIONAL
default 50, max 50
after
integerOPTIONAL
cursor — 傳入上一頁 response 中的 nextCursor(初始值為 0,代表第一頁)以取得下一頁。
status
enumOPTIONAL
pending | success | failed | invalid | blocked | expired | timeout
search
stringOPTIONAL
搜尋目的號碼(子字串比對)

使用 after 時,response 會以 nextCursor + hasMore 取代 total(各狀態的總數請檢視 summary[])。

GET點數餘額

GET https://me-sms.com/api/v2/sms/credit/balance

帳號的點數餘額(傳送大批次前可先查詢)。

GETSender 列表

GET https://me-sms.com/api/v2/senders

帳號內全部的 sender name(含 shared),僅能用 status = "approved" 的 sender 傳送 SMS。

新 sender name 請於系統內的 Senders 頁面 申請(需檔案驗證,不支援透過 API 申請)。