GET
/balance
Ottieni il saldo
Restituisce il saldo attuale del tuo account in dollari USA. Ricezione dei codici e invio di SMS usano lo stesso saldo.
Parametri
Nessun parametro.
Richiesta di esempio
request
$ curl https://today-sms.com/api/v1/balance \
-H "Authorization: Bearer YOUR_API_KEY"
Risposta di esempio
response
{
"balance": "42.5000",
"currency": "USD"
}
Errori possibili
| unauthorized | Chiave API mancante o errata |
| not_allowed | L'API si attiva dopo l'accredito della prima ricarica |
| rate_limited | Troppe richieste in 1 minuto |
GET
/apps
Elenco delle app
Elenca le app che hanno numeri in questo momento. Restituisce codice dell'app, nome, prezzo più basso e numero di paesi con numeri.
Parametri
Nessun parametro.
Richiesta di esempio
request
$ curl https://today-sms.com/api/v1/apps \
-H "Authorization: Bearer YOUR_API_KEY"
Risposta di esempio
response
[
{ "app": "telegram", "name": "Telegram", "from": "0.4515", "countries": 61 }
]
Errori possibili
| unauthorized | Chiave API mancante o errata |
| not_allowed | L'API si attiva dopo l'accredito della prima ricarica |
GET
/prices?app=telegram
Paesi e prezzi di un'app
Restituisce i paesi di un'app, dal più economico. Include prefisso, codice ISO, prezzo e quanti numeri sono disponibili ora.
Parametri
| Nome | Tipo | Obbligatorio | Descrizione |
|---|
| app | string | Obbligatorio | Codice dell'app (il valore app di GET /apps) |
Richiesta di esempio
request
$ curl https://today-sms.com/api/v1/prices?app=telegram \
-H "Authorization: Bearer YOUR_API_KEY"
Risposta di esempio
response
[
{ "country": "indonesia", "iso": "id", "price": "0.4515", "stock": 702866 }
]
Errori possibili
| bad_request | Manca un valore obbligatorio o il formato è errato |
| unauthorized | Chiave API mancante o errata |
POST
/numbers
Acquista un numero
Acquista un numero per l'app e il paese scelti. Il prezzo viene scalato dal saldo e il numero attende gli SMS per il tempo stabilito. Se la conferma del numero richiede più tempo, restituisce 202 con lo stato di verifica in corso.
Parametri
| Nome | Tipo | Obbligatorio | Descrizione |
|---|
| app | string | Obbligatorio | Codice dell'app |
| country | string | Obbligatorio | Codice del paese (il valore country di GET /prices) |
Richiesta di esempio
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"}'
Risposta di esempio
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": []
}
Errori possibili
| bad_request | Manca un valore obbligatorio o il formato è errato |
| not_enough_balance | Saldo insufficiente, ricarica prima |
| too_many_open | Troppi numeri attivi, completane o annullane alcuni |
| no_numbers | Al momento non ci sono numeri per questa app e questo paese |
GET
/numbers/{id}
Stato del numero e SMS
Restituisce lo stato del numero e tutti gli SMS ricevuti finora. Il codice di verifica viene fornito anche a parte in code.
Parametri
| Nome | Tipo | Obbligatorio | Descrizione |
|---|
| id | string | Obbligatorio | L'id ricevuto all'acquisto del numero (inizia con N-) |
Richiesta di esempio
request
$ curl https://today-sms.com/api/v1/numbers/N-7K2M-QX4P-9D3A \
-H "Authorization: Bearer YOUR_API_KEY"
Risposta di esempio
response
{
"id": "N-7K2M-QX4P-9D3A",
"status": "received",
"sms": [
{ "code": "482913", "text": "Your code is 482913", "at": "2026-10-18T09:02:11.000Z" }
]
}
Errori possibili
| not_found | Numero o messaggio non presente nel tuo account |
POST
/numbers/{id}/cancel
Annulla un numero
Annulla un numero che non ha ricevuto SMS, dopo 120 secondi dall'acquisto. L'intero importo torna sul tuo saldo.
Parametri
| Nome | Tipo | Obbligatorio | Descrizione |
|---|
| id | string | Obbligatorio | Id del numero (inizia con N-) |
Richiesta di esempio
request
$ curl -X POST https://today-sms.com/api/v1/numbers/N-7K2M-QX4P-9D3A/cancel \
-H "Authorization: Bearer YOUR_API_KEY"
Risposta di esempio
response
{
"id": "N-7K2M-QX4P-9D3A",
"status": "canceled",
"refunded": "0.4515"
}
Errori possibili
| too_early | Puoi annullare dopo 120 secondi dall'acquisto |
| has_sms | I numeri che hanno ricevuto SMS non si possono annullare |
| try_again | Annullamento non ancora confermato, riprova tra 1 minuto |
| not_found | Numero o messaggio non presente nel tuo account |
POST
/numbers/{id}/finish
Chiudi un numero
Chiude il numero dopo che hai ricevuto il codice. Un numero chiuso non riceve più SMS.
Parametri
| Nome | Tipo | Obbligatorio | Descrizione |
|---|
| id | string | Obbligatorio | Id del numero (inizia con N-) |
Richiesta di esempio
request
$ curl -X POST https://today-sms.com/api/v1/numbers/N-7K2M-QX4P-9D3A/finish \
-H "Authorization: Bearer YOUR_API_KEY"
Risposta di esempio
response
{
"id": "N-7K2M-QX4P-9D3A",
"status": "finished"
}
Errori possibili
| not_found | Numero o messaggio non presente nel tuo account |
GET
/messages/prices
Prezzi SMS per paese
Restituisce il prezzo per SMS di ogni paese per l'invio di SMS. Include codice ISO, prefisso e prezzo per SMS (USD).
Parametri
Nessun parametro.
Richiesta di esempio
request
$ curl https://today-sms.com/api/v1/messages/prices \
-H "Authorization: Bearer YOUR_API_KEY"
Risposta di esempio
response
[
{ "iso": "us", "dial": "1", "price": "0.0042" },
{ "iso": "gb", "dial": "44", "price": "0.0066" }
]
Errori possibili
| unauthorized | Chiave API mancante o errata |
| not_allowed | L'API si attiva dopo l'accredito della prima ricarica |
POST
/messages
Invia SMS
Invia SMS a un elenco di destinatari con il tuo messaggio. Fino a 1.000 destinatari per richiesta, e i numeri duplicati ricevono un solo messaggio. Aggiungi at per programmare l'invio a quell'ora (UTC). Il costo totale viene riservato dal saldo all'invio, e le parti non riuscite vengono rimborsate sul saldo.
Parametri
| Nome | Tipo | Obbligatorio | Descrizione |
|---|
| to | string[] | Obbligatorio | Elenco di numeri in formato internazionale (con + e prefisso), fino a 1.000 |
| text | string | Obbligatorio | Testo del messaggio. 160 caratteri GSM-7 o 70 Unicode sono un SMS |
| at | string | Facoltativo | Ora programmata, ISO 8601 UTC (es. 2026-10-18T10:00:00Z) |
| ref | string | Facoltativo | Un tuo riferimento, come un numero d'ordine, fino a 64 caratteri |
Richiesta di esempio
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"}'
Risposta di esempio
response
{
"id": "m_7Q2K9X",
"status": "queued",
"recipients": 2,
"parts": 1,
"encoding": "GSM-7",
"cost": "0.0136"
}
Errori possibili
| bad_request | Manca un valore obbligatorio o il formato è errato |
| too_many_recipients | Fino a 1.000 destinatari per richiesta |
| not_enough_balance | Saldo insufficiente, ricarica prima |
| not_available | Questo prodotto apre a breve. La richiesta non è stata accettata e il tuo saldo non è cambiato |
GET
/messages/{id}
Stato dell'invio e rapporti di consegna
Restituisce lo stato generale di un messaggio inviato e un rapporto di consegna per ogni destinatario. Gli importi delle parti non riuscite vengono aggiunti a refunded.
Parametri
| Nome | Tipo | Obbligatorio | Descrizione |
|---|
| id | string | Obbligatorio | L'id ricevuto all'invio |
Richiesta di esempio
request
$ curl https://today-sms.com/api/v1/messages/m_7Q2K9X \
-H "Authorization: Bearer YOUR_API_KEY"
Risposta di esempio
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" }
]
}
Errori possibili
| not_found | Numero o messaggio non presente nel tuo account |
POST
/messages/{id}/cancel
Annulla un invio programmato
Annulla un invio programmato che non è ancora partito. L'intero importo riservato torna sul tuo saldo.
Parametri
| Nome | Tipo | Obbligatorio | Descrizione |
|---|
| id | string | Obbligatorio | Id del messaggio |
Richiesta di esempio
request
$ curl -X POST https://today-sms.com/api/v1/messages/m_7Q2K9X/cancel \
-H "Authorization: Bearer YOUR_API_KEY"
Risposta di esempio
response
{
"id": "m_7Q2K9X",
"status": "canceled",
"refunded": "0.0136"
}
Errori possibili
| too_late | I messaggi già in fase di invio non si possono annullare |
| not_found | Numero o messaggio non presente nel tuo account |