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 和確認中的狀態。
| 名稱 | 類型 | 必填 | 說明 |
|---|---|---|---|
| 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 | 必填 | 訊息內容。160 個 GSM-7 字元或 70 個 Unicode 字元為一則簡訊 |
| 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 | 這項商品即將開放。這次請求未被受理，您的餘額也沒有變動 |