GET
/balance
Pobierz saldo
Zwraca aktualne saldo konta w dolarach amerykańskich. Odbiór kodów i wysyłka SMS korzystają z tego samego salda.
Parametry
Brak parametrów.
Przykładowe zapytanie
request
$ curl https://today-sms.com/api/v1/balance \
-H "Authorization: Bearer YOUR_API_KEY"
Przykładowa odpowiedź
response
{
"balance": "42.5000",
"currency": "USD"
}
Możliwe błędy
| unauthorized | Brak klucza API lub klucz jest błędny |
| not_allowed | API otwiera się po zaksięgowaniu pierwszego doładowania |
| rate_limited | Zbyt wiele zapytań w ciągu 1 minuty |
GET
/apps
Lista aplikacji
Wyświetla aplikacje, dla których są teraz numery. Zwraca kod aplikacji, nazwę, najniższą cenę i liczbę krajów z numerami.
Parametry
Brak parametrów.
Przykładowe zapytanie
request
$ curl https://today-sms.com/api/v1/apps \
-H "Authorization: Bearer YOUR_API_KEY"
Przykładowa odpowiedź
response
[
{ "app": "telegram", "name": "Telegram", "from": "0.4515", "countries": 61 }
]
Możliwe błędy
| unauthorized | Brak klucza API lub klucz jest błędny |
| not_allowed | API otwiera się po zaksięgowaniu pierwszego doładowania |
GET
/prices?app=telegram
Kraje i ceny dla aplikacji
Zwraca kraje dla jednej aplikacji, od najtańszego. Zawiera kod kraju, kod ISO, cenę i liczbę numerów dostępnych w tej chwili.
Parametry
| Nazwa | Typ | Wymagany | Opis |
|---|
| app | string | Wymagany | Kod aplikacji (wartość app z GET /apps) |
Przykładowe zapytanie
request
$ curl https://today-sms.com/api/v1/prices?app=telegram \
-H "Authorization: Bearer YOUR_API_KEY"
Przykładowa odpowiedź
response
[
{ "country": "indonesia", "iso": "id", "price": "0.4515", "stock": 702866 }
]
Możliwe błędy
| bad_request | Brakuje wymaganej wartości lub ma ona zły format |
| unauthorized | Brak klucza API lub klucz jest błędny |
POST
/numbers
Kup numer
Kupuje numer dla wybranej aplikacji i kraju. Cena zostaje pobrana z salda, a numer czeka na SMS przez ustalony czas. Jeśli potwierdzenie numeru trwa dłużej, zwraca 202 ze statusem checking.
Parametry
| Nazwa | Typ | Wymagany | Opis |
|---|
| app | string | Wymagany | Kod aplikacji |
| country | string | Wymagany | Kod kraju (wartość country z GET /prices) |
Przykładowe zapytanie
request
$ 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"}'
Przykładowa odpowiedź
response
{
"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": []
}
Możliwe błędy
| bad_request | Brakuje wymaganej wartości lub ma ona zły format |
| not_enough_balance | Za mało środków, najpierw doładuj saldo |
| too_many_open | Za dużo otwartych numerów, zakończ lub anuluj kilka z nich |
| no_numbers | Obecnie brak numerów dla tej aplikacji i kraju |
GET
/numbers/{id}
Status numeru i SMS
Zwraca status numeru i wszystkie dotąd odebrane SMS. Kod weryfikacyjny jest dodatkowo podany osobno w polu code.
Parametry
| Nazwa | Typ | Wymagany | Opis |
|---|
| id | string | Wymagany | id otrzymane przy zakupie numeru (zaczyna się od N-) |
Przykładowe zapytanie
request
$ curl https://today-sms.com/api/v1/numbers/N-7K2M-QX4P-9D3A \
-H "Authorization: Bearer YOUR_API_KEY"
Przykładowa odpowiedź
response
{
"id": "N-7K2M-QX4P-9D3A",
"status": "received",
"sms": [
{ "code": "482913", "text": "Your code is 482913", "at": "2026-10-18T09:02:11.000Z" }
]
}
Możliwe błędy
| not_found | Na Twoim koncie nie ma takiego numeru ani wiadomości |
POST
/numbers/{id}/cancel
Anuluj numer
Anuluje numer, na który nie dotarł żaden SMS, po 120 s od zakupu. Cała kwota wraca na saldo.
Parametry
| Nazwa | Typ | Wymagany | Opis |
|---|
| id | string | Wymagany | id numeru (zaczyna się od N-) |
Przykładowe zapytanie
request
$ curl -X POST https://today-sms.com/api/v1/numbers/N-7K2M-QX4P-9D3A/cancel \
-H "Authorization: Bearer YOUR_API_KEY"
Przykładowa odpowiedź
response
{
"id": "N-7K2M-QX4P-9D3A",
"status": "canceled",
"refunded": "0.4515"
}
Możliwe błędy
| too_early | Anulować możesz po 120 s od zakupu |
| has_sms | Numerów, na które dotarł SMS, nie można anulować |
| try_again | Anulowanie nie zostało jeszcze potwierdzone, spróbuj ponownie za 1 minutę |
| not_found | Na Twoim koncie nie ma takiego numeru ani wiadomości |
POST
/numbers/{id}/finish
Zakończ numer
Zamyka numer po odebraniu kodu. Zamknięty numer nie odbiera już SMS.
Parametry
| Nazwa | Typ | Wymagany | Opis |
|---|
| id | string | Wymagany | id numeru (zaczyna się od N-) |
Przykładowe zapytanie
request
$ curl -X POST https://today-sms.com/api/v1/numbers/N-7K2M-QX4P-9D3A/finish \
-H "Authorization: Bearer YOUR_API_KEY"
Przykładowa odpowiedź
response
{
"id": "N-7K2M-QX4P-9D3A",
"status": "finished"
}
Możliwe błędy
| not_found | Na Twoim koncie nie ma takiego numeru ani wiadomości |
GET
/messages/prices
Ceny SMS według kraju
Zwraca cenę za SMS dla każdego kraju przy wysyłce SMS. Zawiera kod ISO, numer kierunkowy i cenę za SMS (USD).
Parametry
Brak parametrów.
Przykładowe zapytanie
request
$ curl https://today-sms.com/api/v1/messages/prices \
-H "Authorization: Bearer YOUR_API_KEY"
Przykładowa odpowiedź
response
[
{ "iso": "us", "dial": "1", "price": "0.0042" },
{ "iso": "gb", "dial": "44", "price": "0.0066" }
]
Możliwe błędy
| unauthorized | Brak klucza API lub klucz jest błędny |
| not_allowed | API otwiera się po zaksięgowaniu pierwszego doładowania |
POST
/messages
Wyślij SMS
Wysyła SMS z Twoją wiadomością do listy odbiorców. Do 1000 odbiorców na zapytanie, a na powtórzone numery idzie tylko jedna wiadomość. Dodaj at, aby zaplanować wysyłkę na ten czas (UTC). Łączny koszt zostaje zablokowany na saldzie przy wysyłce, a za nieudane części dostajesz zwrot na saldo.
Parametry
| Nazwa | Typ | Wymagany | Opis |
|---|
| to | string[] | Wymagany | Lista numerów w formacie międzynarodowym (z + i numerem kierunkowym), do 1000 |
| text | string | Wymagany | Treść wiadomości. 160 znaków GSM-7 lub 70 znaków Unicode to jeden SMS |
| at | string | Opcjonalny | Zaplanowany czas, ISO 8601 UTC (np. 2026-10-18T10:00:00Z) |
| ref | string | Opcjonalny | Własne oznaczenie, na przykład numer zamówienia, do 64 znaków |
Przykładowe zapytanie
request
$ 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"}'
Przykładowa odpowiedź
response
{
"id": "m_7Q2K9X",
"status": "queued",
"recipients": 2,
"parts": 1,
"encoding": "GSM-7",
"cost": "0.0136"
}
Możliwe błędy
| bad_request | Brakuje wymaganej wartości lub ma ona zły format |
| too_many_recipients | Do 1000 odbiorców na zapytanie |
| not_enough_balance | Za mało środków, najpierw doładuj saldo |
| not_available | Ten produkt wkrótce ruszy. To zapytanie nie zostało przyjęte, a saldo się nie zmieniło |
GET
/messages/{id}
Status wysyłki i raporty doręczenia
Zwraca ogólny status wysłanej wiadomości i raport doręczenia dla każdego odbiorcy. Kwoty za nieudane części są dodawane do refunded.
Parametry
| Nazwa | Typ | Wymagany | Opis |
|---|
| id | string | Wymagany | id otrzymane przy wysyłce |
Przykładowe zapytanie
request
$ curl https://today-sms.com/api/v1/messages/m_7Q2K9X \
-H "Authorization: Bearer YOUR_API_KEY"
Przykładowa odpowiedź
response
{
"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" }
]
}
Możliwe błędy
| not_found | Na Twoim koncie nie ma takiego numeru ani wiadomości |
POST
/messages/{id}/cancel
Anuluj zaplanowaną wysyłkę
Anuluje zaplanowaną wysyłkę, która jeszcze nie ruszyła. Cała zablokowana kwota wraca na saldo.
Parametry
| Nazwa | Typ | Wymagany | Opis |
|---|
| id | string | Wymagany | id wiadomości |
Przykładowe zapytanie
request
$ curl -X POST https://today-sms.com/api/v1/messages/m_7Q2K9X/cancel \
-H "Authorization: Bearer YOUR_API_KEY"
Przykładowa odpowiedź
response
{
"id": "m_7Q2K9X",
"status": "canceled",
"refunded": "0.0136"
}
Możliwe błędy
| too_late | Wiadomości, których wysyłka już ruszyła, nie można anulować |
| not_found | Na Twoim koncie nie ma takiego numeru ani wiadomości |