API
TODAY SMS API 是基於 HTTPS 的 JSON API。所有請求都以 Authorization 標頭傳送 API 金鑰。價格、退款及 20 分鐘等候時間與網站相同。在清單中選擇方法，即可查看請求及回應範例。
查詢餘額
以美元回傳賬戶現時餘額。接收驗證碼及發送短訊共用同一餘額。
沒有請求參數。
$ curl https://today-sms.com/api/v1/balance \
-H "Authorization: Bearer YOUR_API_KEY"
{
"balance": "42.5000",
"currency": "USD"
}
| unauthorized | API 金鑰缺少或不正確 |
| not_allowed | 首次增值入賬後才會開放 API |
| rate_limited | 1 分鐘內請求太多 |
App 清單
現時有號碼的 App 清單，回傳 App 代碼、名稱、最低價格及有號碼的國家數目。
沒有請求參數。
$ curl https://today-sms.com/api/v1/apps \
-H "Authorization: Bearer YOUR_API_KEY"
[
{ "app": "telegram", "name": "Telegram", "from": "0.4515", "countries": 61 }
]
| unauthorized | API 金鑰缺少或不正確 |
| not_allowed | 首次增值入賬後才會開放 API |
各 App 的國家及價格
按價格由低至高回傳某個 App 的國家清單，包括國家代碼、ISO 代碼、價格及現有號碼數目。
| 名稱 | 類型 | 必填 | 說明 |
|---|---|---|---|
| app | string | 必填 | App 代碼（GET /apps 的 app 值） |
$ curl https://today-sms.com/api/v1/prices?app=telegram \
-H "Authorization: Bearer YOUR_API_KEY"
[
{ "country": "indonesia", "iso": "id", "price": "0.4515", "stock": 702866 }
]
| bad_request | 缺少必填值或格式不正確 |
| unauthorized | API 金鑰缺少或不正確 |
購買號碼
指定 App 和國家購買號碼。款項從餘額扣除，號碼會在指定時間內等候短訊。如號碼確認需時，會以 202 及 checking 狀態回傳。
| 名稱 | 類型 | 必填 | 說明 |
|---|---|---|---|
| app | string | 必填 | App 代碼 |
| country | string | 必填 | 國家代碼（GET /prices 的 country 值） |
$ curl -X POST https://today-sms.com/api/v1/numbers \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"app":"telegram","country":"indonesia"}'
{
"id": "N-7K2M-QX4P-9D3A",
"app": "telegram",
"country": "indonesia",
"phone": "+6281234567890",
"price": "0.4515",
"refunded": "0.0000",
"status": "waiting",
"expires_at": "2026-10-18T09:20:00.000Z",
"sms": []
}
| bad_request | 缺少必填值或格式不正確 |
| not_enough_balance | 餘額不足，請先增值 |
| too_many_open | 開啟中的號碼太多，請完成或取消部分號碼 |
| no_numbers | 此 App 及國家現時沒有號碼 |
號碼狀態及短訊
回傳號碼狀態及至今收到的所有短訊。驗證碼另外放在 code 內。
| 名稱 | 類型 | 必填 | 說明 |
|---|---|---|---|
| id | string | 必填 | 購買號碼時取得的 id（以 N- 開頭） |
$ curl https://today-sms.com/api/v1/numbers/N-7K2M-QX4P-9D3A \
-H "Authorization: Bearer YOUR_API_KEY"
{
"id": "N-7K2M-QX4P-9D3A",
"status": "received",
"sms": [
{ "code": "482913", "text": "Your code is 482913", "at": "2026-10-18T09:02:11.000Z" }
]
}
| not_found | 您的賬戶中沒有此號碼或短訊 |
取消號碼
在購買 120 秒後取消未收到短訊的號碼，全數款項退回餘額。
| 名稱 | 類型 | 必填 | 說明 |
|---|---|---|---|
| id | string | 必填 | 號碼 id（以 N- 開頭） |
$ curl -X POST https://today-sms.com/api/v1/numbers/N-7K2M-QX4P-9D3A/cancel \
-H "Authorization: Bearer YOUR_API_KEY"
{
"id": "N-7K2M-QX4P-9D3A",
"status": "canceled",
"refunded": "0.4515"
}
| too_early | 購買 120 秒後才可取消 |
| has_sms | 已收到短訊的號碼不能取消 |
| try_again | 取消尚未確認，請 1 分鐘後再試 |
| not_found | 您的賬戶中沒有此號碼或短訊 |
完成號碼
收到驗證碼後關閉號碼。已關閉的號碼不會再接收短訊。
| 名稱 | 類型 | 必填 | 說明 |
|---|---|---|---|
| id | string | 必填 | 號碼 id（以 N- 開頭） |
$ curl -X POST https://today-sms.com/api/v1/numbers/N-7K2M-QX4P-9D3A/finish \
-H "Authorization: Bearer YOUR_API_KEY"
{
"id": "N-7K2M-QX4P-9D3A",
"status": "finished"
}
| not_found | 您的賬戶中沒有此號碼或短訊 |
各國短訊價格
回傳發送短訊的各國每條價格，包括 ISO 代碼、國碼及每條價格（USD）。
沒有請求參數。
$ curl https://today-sms.com/api/v1/messages/prices \
-H "Authorization: Bearer YOUR_API_KEY"
[
{ "iso": "us", "dial": "1", "price": "0.0042" },
{ "iso": "gb", "dial": "44", "price": "0.0066" }
]
| unauthorized | API 金鑰缺少或不正確 |
| not_allowed | 首次增值入賬後才會開放 API |
發送短訊
以收件人清單及內容發送短訊。每個請求最多 1,000 人，同一號碼只發送一次。加入 at 便會在該時間（UTC）預約發送。總費用會在發送時從餘額預留，失敗的短訊款項會退回餘額。
| 名稱 | 類型 | 必填 | 說明 |
|---|---|---|---|
| to | string[] | 必填 | 國際格式號碼清單（包括 + 及國碼），最多 1,000 個 |
| text | string | 必填 | 內容。GSM-7 160 字或 Unicode 70 字為一條 |
| at | string | 選填 | 預約時間，ISO 8601 UTC（例如 2026-10-18T10:00:00Z） |
| ref | string | 選填 | 您自己的訂單編號等參考值，最多 64 字 |
$ curl -X POST https://today-sms.com/api/v1/messages \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"to":["+14155550100","+447700900123"],"text":"Your code is 482913"}'
{
"id": "m_7Q2K9X",
"status": "queued",
"recipients": 2,
"parts": 1,
"encoding": "GSM-7",
"cost": "0.0136"
}
| bad_request | 缺少必填值或格式不正確 |
| too_many_recipients | 每個請求最多 1,000 位收件人 |
| not_enough_balance | 餘額不足，請先增值 |
| not_available | 此產品即將開放，今次請求未有受理，餘額保持不變 |
發送狀態及送達報告
回傳已發送短訊的整體狀態及每位收件人的送達報告。失敗短訊的款項會加到 refunded。
| 名稱 | 類型 | 必填 | 說明 |
|---|---|---|---|
| id | string | 必填 | 發送短訊時取得的 id |
$ curl https://today-sms.com/api/v1/messages/m_7Q2K9X \
-H "Authorization: Bearer YOUR_API_KEY"
{
"id": "m_7Q2K9X",
"status": "done",
"cost": "0.0136",
"refunded": "0.0083",
"reports": [
{ "to": "+14155550100", "status": "delivered", "at": "2026-10-18T10:00:04Z" },
{ "to": "+447700900123", "status": "failed", "at": "2026-10-18T10:00:09Z" }
]
}
| not_found | 您的賬戶中沒有此號碼或短訊 |
取消預約發送
取消尚未發送的預約發送，預留的款項會全數退回餘額。
| 名稱 | 類型 | 必填 | 說明 |
|---|---|---|---|
| id | string | 必填 | 短訊 id |
$ curl -X POST https://today-sms.com/api/v1/messages/m_7Q2K9X/cancel \
-H "Authorization: Bearer YOUR_API_KEY"
{
"id": "m_7Q2K9X",
"status": "canceled",
"refunded": "0.0136"
}
| too_late | 已開始發送的短訊不能取消 |
| not_found | 您的賬戶中沒有此號碼或短訊 |
https://today-sms.com/api/v1
標頭 Authorization: Bearer YOUR_API_KEY。首次增值入賬後，可在 API 金鑰頁面建立金鑰。每分鐘最多可發出 300 次請求。
$ curl https://today-sms.com/api/v1/balance \
-H "Authorization: Bearer YOUR_API_KEY"
請求內容及回應均為 JSON（UTF-8）。金額為美元字串，最多 4 個小數位；時間為 ISO 8601 UTC。
| waiting | 號碼已準備好，尚未收到短訊 |
| received | 已收到一條或以上短訊 |
| finished | 收到驗證碼後已關閉 |
| canceled | 已取消，全額退款 |
| expired | 時限內未收到短訊，全額退款 |
| checking | 正在確認號碼，時限結束前仍無號碼便退款 |
| queued | 等候發送 |
| scheduled | 已預約，會在指定時間發送 |
| sending | 發送中 |
| done | 所有收件人已有結果 |
| canceled | 預約已取消，全額退款 |
| pending | 尚未交給電訊商 |
| sent | 已交給電訊商 |
| delivered | 已送達收件人手機 |
| failed | 失敗，該條短訊款項退回餘額 |
錯誤會以非 2xx 的狀態碼及包含 error 值的 JSON 回傳。
{
"error": "not_enough_balance"
}
| unauthorized | API 金鑰缺少或不正確 |
| not_allowed | 首次增值入賬後才會開放 API |
| bad_request | 缺少必填值或格式不正確 |
| no_numbers | 此 App 及國家現時沒有號碼 |
| not_enough_balance | 餘額不足，請先增值 |
| too_many_open | 開啟中的號碼太多，請完成或取消部分號碼 |
| too_early | 購買 120 秒後才可取消 |
| has_sms | 已收到短訊的號碼不能取消 |
| not_found | 您的賬戶中沒有此號碼或短訊 |
| try_again | 取消尚未確認，請 1 分鐘後再試 |
| rate_limited | 1 分鐘內請求太多 |
| too_many_recipients | 每個請求最多 1,000 位收件人 |
| too_late | 已開始發送的短訊不能取消 |
| not_available | 此產品即將開放，今次請求未有受理，餘額保持不變 |