GET
/balance
Guthaben abfragen
Liefert das aktuelle Guthaben Ihres Kontos in US-Dollar. Codeempfang und SMS-Versand nutzen dasselbe Guthaben.
Parameter
Keine Parameter.
Beispielanfrage
request
$ curl https://today-sms.com/api/v1/balance \
-H "Authorization: Bearer YOUR_API_KEY"
Beispielantwort
response
{
"balance": "42.5000",
"currency": "USD"
}
Mögliche Fehler
| unauthorized | API-Schlüssel fehlt oder ist falsch |
| not_allowed | Die API steht nach Gutschrift Ihrer ersten Aufladung bereit |
| rate_limited | Zu viele Anfragen in 1 Minute |
GET
/apps
Apps auflisten
Listet Apps, für die es gerade Nummern gibt. Liefert App-Code, Name, günstigsten Preis und die Anzahl der Länder mit Nummern.
Parameter
Keine Parameter.
Beispielanfrage
request
$ curl https://today-sms.com/api/v1/apps \
-H "Authorization: Bearer YOUR_API_KEY"
Beispielantwort
response
[
{ "app": "telegram", "name": "Telegram", "from": "0.4515", "countries": 61 }
]
Mögliche Fehler
| unauthorized | API-Schlüssel fehlt oder ist falsch |
| not_allowed | Die API steht nach Gutschrift Ihrer ersten Aufladung bereit |
GET
/prices?app=telegram
Länder und Preise einer App
Liefert die Länder einer App, günstigste zuerst. Enthält Ländervorwahl, ISO-Code, Preis und die Anzahl der gerade verfügbaren Nummern.
Parameter
| Name | Typ | Pflicht | Beschreibung |
|---|
| app | string | Pflicht | App-Code (der app-Wert aus GET /apps) |
Beispielanfrage
request
$ curl https://today-sms.com/api/v1/prices?app=telegram \
-H "Authorization: Bearer YOUR_API_KEY"
Beispielantwort
response
[
{ "country": "indonesia", "iso": "id", "price": "0.4515", "stock": 702866 }
]
Mögliche Fehler
| bad_request | Ein Pflichtwert fehlt oder hat das falsche Format |
| unauthorized | API-Schlüssel fehlt oder ist falsch |
POST
/numbers
Nummer kaufen
Kauft eine Nummer für die gewählte App und das gewählte Land. Der Preis wird vom Guthaben abgebucht, und die Nummer wartet die festgelegte Zeit auf SMS. Dauert die Bestätigung der Nummer länger, kommt 202 mit dem Status checking zurück.
Parameter
| Name | Typ | Pflicht | Beschreibung |
|---|
| app | string | Pflicht | App-Code |
| country | string | Pflicht | Ländercode (der country-Wert aus GET /prices) |
Beispielanfrage
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"}'
Beispielantwort
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": []
}
Mögliche Fehler
| bad_request | Ein Pflichtwert fehlt oder hat das falsche Format |
| not_enough_balance | Guthaben zu niedrig, bitte zuerst aufladen |
| too_many_open | Zu viele aktive Nummern, bitte einige abschließen oder stornieren |
| no_numbers | Für diese App und dieses Land gibt es gerade keine Nummern |
GET
/numbers/{id}
Nummernstatus und SMS
Liefert den Status der Nummer und jede bisher empfangene SMS. Der Bestätigungscode steht zusätzlich separat in code.
Parameter
| Name | Typ | Pflicht | Beschreibung |
|---|
| id | string | Pflicht | Die id, die Sie beim Kauf der Nummer erhalten haben (beginnt mit N-) |
Beispielanfrage
request
$ curl https://today-sms.com/api/v1/numbers/N-7K2M-QX4P-9D3A \
-H "Authorization: Bearer YOUR_API_KEY"
Beispielantwort
response
{
"id": "N-7K2M-QX4P-9D3A",
"status": "received",
"sms": [
{ "code": "482913", "text": "Your code is 482913", "at": "2026-10-18T09:02:11.000Z" }
]
}
Mögliche Fehler
| not_found | Diese Nummer oder Nachricht gibt es in Ihrem Konto nicht |
POST
/numbers/{id}/cancel
Nummer stornieren
Storniert eine Nummer ohne empfangene SMS, ab 120 Sekunden nach dem Kauf. Der volle Betrag geht zurück auf Ihr Guthaben.
Parameter
| Name | Typ | Pflicht | Beschreibung |
|---|
| id | string | Pflicht | Nummern-id (beginnt mit N-) |
Beispielanfrage
request
$ curl -X POST https://today-sms.com/api/v1/numbers/N-7K2M-QX4P-9D3A/cancel \
-H "Authorization: Bearer YOUR_API_KEY"
Beispielantwort
response
{
"id": "N-7K2M-QX4P-9D3A",
"status": "canceled",
"refunded": "0.4515"
}
Mögliche Fehler
| too_early | Stornieren ist ab 120 Sekunden nach dem Kauf möglich |
| has_sms | Nummern, die SMS empfangen haben, lassen sich nicht stornieren |
| try_again | Stornierung noch nicht bestätigt, bitte in 1 Minute erneut versuchen |
| not_found | Diese Nummer oder Nachricht gibt es in Ihrem Konto nicht |
POST
/numbers/{id}/finish
Nummer abschließen
Schließt die Nummer nach Erhalt des Codes. Eine geschlossene Nummer empfängt keine SMS mehr.
Parameter
| Name | Typ | Pflicht | Beschreibung |
|---|
| id | string | Pflicht | Nummern-id (beginnt mit N-) |
Beispielanfrage
request
$ curl -X POST https://today-sms.com/api/v1/numbers/N-7K2M-QX4P-9D3A/finish \
-H "Authorization: Bearer YOUR_API_KEY"
Beispielantwort
response
{
"id": "N-7K2M-QX4P-9D3A",
"status": "finished"
}
Mögliche Fehler
| not_found | Diese Nummer oder Nachricht gibt es in Ihrem Konto nicht |
GET
/messages/prices
SMS-Preise nach Land
Liefert den Preis pro SMS je Land für den SMS-Versand. Enthält ISO-Code, Ländervorwahl und Preis pro SMS (USD).
Parameter
Keine Parameter.
Beispielanfrage
request
$ curl https://today-sms.com/api/v1/messages/prices \
-H "Authorization: Bearer YOUR_API_KEY"
Beispielantwort
response
[
{ "iso": "us", "dial": "1", "price": "0.0042" },
{ "iso": "gb", "dial": "44", "price": "0.0066" }
]
Mögliche Fehler
| unauthorized | API-Schlüssel fehlt oder ist falsch |
| not_allowed | Die API steht nach Gutschrift Ihrer ersten Aufladung bereit |
POST
/messages
SMS senden
Sendet SMS mit Ihrer Nachricht an eine Empfängerliste. Bis zu 1.000 Empfänger pro Anfrage, doppelte Nummern erhalten nur eine Nachricht. Mit at planen Sie den Versand für diese Zeit (UTC). Die Gesamtkosten werden beim Senden im Guthaben reserviert, fehlgeschlagene Teile werden dem Guthaben erstattet.
Parameter
| Name | Typ | Pflicht | Beschreibung |
|---|
| to | string[] | Pflicht | Liste von Nummern im internationalen Format (mit + und Ländervorwahl), bis zu 1.000 |
| text | string | Pflicht | Nachrichtentext. 160 GSM-7- oder 70 Unicode-Zeichen sind eine SMS |
| at | string | Optional | Geplante Zeit, ISO 8601 UTC (z. B. 2026-10-18T10:00:00Z) |
| ref | string | Optional | Ihre eigene Referenz, etwa eine Bestellnummer, bis zu 64 Zeichen |
Beispielanfrage
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"}'
Beispielantwort
response
{
"id": "m_7Q2K9X",
"status": "queued",
"recipients": 2,
"parts": 1,
"encoding": "GSM-7",
"cost": "0.0136"
}
Mögliche Fehler
| bad_request | Ein Pflichtwert fehlt oder hat das falsche Format |
| too_many_recipients | Bis zu 1.000 Empfänger pro Anfrage |
| not_enough_balance | Guthaben zu niedrig, bitte zuerst aufladen |
| not_available | Dieses Produkt startet bald. Diese Anfrage wurde nicht angenommen, Ihr Guthaben bleibt unverändert |
GET
/messages/{id}
Versandstatus und Zustellberichte
Liefert den Gesamtstatus einer gesendeten Nachricht und einen Zustellbericht je Empfänger. Beträge für fehlgeschlagene Teile werden zu refunded addiert.
Parameter
| Name | Typ | Pflicht | Beschreibung |
|---|
| id | string | Pflicht | Die id, die Sie beim Senden erhalten haben |
Beispielanfrage
request
$ curl https://today-sms.com/api/v1/messages/m_7Q2K9X \
-H "Authorization: Bearer YOUR_API_KEY"
Beispielantwort
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" }
]
}
Mögliche Fehler
| not_found | Diese Nummer oder Nachricht gibt es in Ihrem Konto nicht |
POST
/messages/{id}/cancel
Geplanten Versand stornieren
Storniert einen geplanten Versand, der noch nicht erfolgt ist. Der volle reservierte Betrag geht zurück auf Ihr Guthaben.
Parameter
| Name | Typ | Pflicht | Beschreibung |
|---|
| id | string | Pflicht | Nachrichten-id |
Beispielanfrage
request
$ curl -X POST https://today-sms.com/api/v1/messages/m_7Q2K9X/cancel \
-H "Authorization: Bearer YOUR_API_KEY"
Beispielantwort
response
{
"id": "m_7Q2K9X",
"status": "canceled",
"refunded": "0.0136"
}
Mögliche Fehler
| too_late | Nachrichten, deren Versand begonnen hat, lassen sich nicht stornieren |
| not_found | Diese Nummer oder Nachricht gibt es in Ihrem Konto nicht |