API
TODAY SMS APIは、HTTPS上のJSON APIです。すべてのリクエストでAPIキーをAuthorizationヘッダーで送ります。料金、返金、20分の待機時間はWebサイトと同じです。一覧からメソッドを選ぶと、リクエストとレスポンスの例が表示されます。
残高の確認
アカウントの現在の残高を米ドルで返します。認証コードの受信とSMS送信は同じ残高を使います。
リクエストパラメーターはありません。
$ 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分間のリクエストが多すぎます |
アプリ一覧
現在番号があるアプリの一覧です。アプリコード、名前、最安料金、番号がある国の数を返します。
リクエストパラメーターはありません。
$ 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は初回チャージが反映されたあとに使えるようになります |
アプリ別の国と料金
1つのアプリの国一覧を安い順に返します。国コード、ISOコード、料金、現在ある番号の数が含まれます。
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| app | string | 必須 | アプリコード(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キーがないか、正しくありません |
番号の購入
アプリと国を指定して番号を購入します。料金は残高から差し引かれ、番号は決まった時間のあいだSMSを待ちます。番号の確認が遅れると、202とともにcheckingの状態で返されます。
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| app | string | 必須 | アプリコード |
| 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 | 現在このアプリと国の番号はありません |
番号の状態とSMS
番号の状態と、これまでに受信したSMSをすべて返します。認証コードは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 | ご自身のアカウントに該当する番号やSMSがありません |
番号のキャンセル
SMSが届いていない番号を、購入から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 | SMSが届いた番号はキャンセルできません |
| try_again | キャンセルがまだ確認されていません。1分後にもう一度お試しください |
| not_found | ご自身のアカウントに該当する番号やSMSがありません |
番号の終了
認証コードを受け取ったあとに番号を閉じます。閉じた番号はそれ以上SMSを受信しません。
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| 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 | ご自身のアカウントに該当する番号やSMSがありません |
国別SMS料金
SMS送信の国別の1通あたりの料金を返します。ISOコード、国番号、1通あたりの料金(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は初回チャージが反映されたあとに使えるようになります |
SMS送信
宛先の一覧と本文でSMSを送信します。1回のリクエストで最大1,000人、同じ番号には1回だけ送ります。atを入れるとその時刻(UTC)に送る予約送信になります。合計費用は送信時に残高から確保し、失敗した通数分は残高にお返しします。
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| to | string[] | 必須 | 国際形式の番号の一覧(+と国番号を含む)、最大1,000件 |
| text | string | 必須 | 本文。GSM-7 160文字、Unicode 70文字で1通 |
| 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回のリクエストの宛先は1,000人までです |
| not_enough_balance | 残高が不足しています。先にチャージしてください |
| not_available | このサービスはまもなく利用できるようになります。今回のリクエストは受け付けておらず、残高はそのままです |
送信状態と配信レポート
送ったSMSの全体の状態と、宛先別の配信レポートを返します。失敗した通数分の金額はrefundedに加算されます。
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| id | string | 必須 | SMS送信時に受け取った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 | ご自身のアカウントに該当する番号やSMSがありません |
予約送信のキャンセル
まだ送っていない予約送信をキャンセルします。確保していた金額はすべて残高に戻ります。
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| id | string | 必須 | SMSの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 | すでに送信を開始したSMSはキャンセルできません |
| not_found | ご自身のアカウントに該当する番号やSMSがありません |
https://today-sms.com/api/v1
ヘッダー Authorization: Bearer YOUR_API_KEY。キーは初回チャージが反映されたあとにAPIキーページで作成します。1分あたり300回までリクエストできます。
$ curl https://today-sms.com/api/v1/balance \
-H "Authorization: Bearer YOUR_API_KEY"
リクエスト本文とレスポンスはJSON(UTF-8)です。金額は米ドルの文字列で小数点以下4桁まで、時刻はISO 8601 UTCです。
| waiting | 番号の準備完了、まだSMSなし |
| received | SMSが1通以上到着 |
| finished | 認証コードを受け取ったあとに終了 |
| canceled | キャンセル、全額返金 |
| expired | 時間内にSMSがなく全額返金 |
| 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 | 現在このアプリと国の番号はありません |
| not_enough_balance | 残高が不足しています。先にチャージしてください |
| too_many_open | 開いている番号が多すぎます。いくつか終了するかキャンセルしてください |
| too_early | 購入から120秒後からキャンセルできます |
| has_sms | SMSが届いた番号はキャンセルできません |
| not_found | ご自身のアカウントに該当する番号やSMSがありません |
| try_again | キャンセルがまだ確認されていません。1分後にもう一度お試しください |
| rate_limited | 1分間のリクエストが多すぎます |
| too_many_recipients | 1回のリクエストの宛先は1,000人までです |
| too_late | すでに送信を開始したSMSはキャンセルできません |
| not_available | このサービスはまもなく利用できるようになります。今回のリクエストは受け付けておらず、残高はそのままです |