API
TODAY SMS API는 HTTPS 위의 JSON API예요. 모든 요청에 API 키를 Authorization 머리글로 보내요. 가격, 환불, 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분 동안 요청이 너무 많아요 |
앱 목록
지금 번호가 있는 앱 목록이에요. 앱 코드, 이름, 가장 싼 가격, 번호가 있는 나라 수를 돌려줘요.
요청 값이 없어요.
$ 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는 첫 충전이 반영된 뒤 열려요 |
앱별 나라와 가격
한 앱의 나라 목록을 싼 순서로 돌려줘요. 나라 코드, 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 키가 없거나 틀려요 |
번호 구매
앱과 나라를 정해 번호를 사요. 가격은 크레딧에서 빠지고, 번호는 정해진 시간 동안 문자를 기다려요. 번호 확인이 늦어지면 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 | 지금 이 앱과 나라에 번호가 없어요 |
번호 상태와 문자
번호의 상태와 지금까지 받은 문자를 모두 돌려줘요. 인증번호는 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자, 유니코드 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 키 페이지에서 만들어요. 1분에 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 | 지금 이 앱과 나라에 번호가 없어요 |
| 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 | 이 상품은 곧 열려요, 이번 요청은 접수되지 않았고 크레딧은 그대로예요 |