smstome APIsmstome.com ↗
Access temporary phone numbers and incoming SMS messages from smstome.com. List countries, browse numbers by country, read messages, and search by keyword.
What is the smstome API?
The smstome.com API exposes 4 endpoints for browsing temporary phone numbers and reading incoming SMS messages across currently 6 supported countries. Starting with list_countries, you can retrieve country slugs, then page through available numbers via list_phone_numbers, and pull or search message history for any number using the sms_id returned alongside each phone number entry.
No input parameters required.
curl -X GET 'https://api.parse.bot/scraper/9d0f9dc7-f182-4bd8-a1eb-1965e3d0121a/list_countries' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace smstome-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
from parse_apis.smstome.com_phone_numbers___messages_api import SMSToMe, CountrySlug, PhoneNumberNotFound
sms = SMSToMe()
# List all available countries
for country in sms.countries.list():
print(country.name, country.slug)
# Browse phone numbers for Netherlands using the enum
netherlands = sms.country(CountrySlug.NETHERLANDS)
for phone in netherlands.phone_numbers.list(limit=5):
print(phone.phone_number, phone.added, phone.sms_id)
# Read incoming messages for this number
for msg in phone.messages.list(limit=3):
print(msg.from_, msg.received, msg.message)
# Search for Signal verification codes
for msg in phone.messages.search(query="signal"):
print(msg.from_, msg.received, msg.message)
List all available countries that have temporary phone numbers on smstome.com. Returns deduplicated country entries with slugs usable in other endpoints. The set is small (currently 6 countries) and returned in a single page.
No input parameters required.
{
"type": "object",
"fields": {
"total": "integer total number of unique countries",
"countries": "array of objects with name, slug, and url for each country"
},
"sample": {
"data": {
"total": 4,
"countries": [
{
"url": "https://smstome.com/country/united-kingdom",
"name": "United Kingdom+44",
"slug": "united-kingdom"
},
{
"url": "https://smstome.com/country/finland",
"name": "Finland+358",
"slug": "finland"
},
{
"url": "https://smstome.com/country/netherlands",
"name": "Netherlands+31",
"slug": "netherlands"
},
{
"url": "https://smstome.com/country/poland",
"name": "Poland+48",
"slug": "poland"
}
]
},
"status": "success"
}
}About the smstome API
Country and Phone Number Coverage
The list_countries endpoint returns all countries that currently have temporary numbers on smstome.com — a deduplicated list of up to 6 countries, each with a name, slug, and url. Those slugs feed directly into list_phone_numbers, which accepts a country slug and optional page parameter and returns 20 numbers per page. Each number entry includes phone_number, country_code, added timestamp, sms_id, and sms_url. The sms_id is required by both message endpoints.
Reading and Searching Messages
get_messages retrieves SMS messages for a specific number identified by number, sms_id, and country. Messages are paginated 10 per page, ordered newest to oldest. Each message object contains from (sender), received (timestamp), and message (body). If no messages exist or the requested page is out of range, the endpoint returns an empty messages array rather than an error.
Keyword Search Across Message History
search_messages scans a number's message history for entries where either the from field or the message body contains a case-insensitive match against the query parameter. Optional start_page and max_pages parameters control which portion of the history is scanned, each page covering 10 messages. The response includes pages_scanned, total_pages_available, and the matched messages array, giving you visibility into how much history was actually checked.
The smstome API is a managed, monitored endpoint for smstome.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when smstome.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official smstome.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Verify which temporary phone numbers are currently available in a given country using
list_phone_numberswith a country slug - Monitor incoming OTP or verification SMS messages on a temporary number by polling
get_messagesfor new entries - Search a number's full message history for a specific service name or keyword using
search_messageswith a targeted query - Track when new numbers were added to a country's pool via the
addedfield inlist_phone_numbersresults - Enumerate all supported country slugs with
list_countriesbefore building country-specific workflows - Identify which sender is messaging a number by inspecting the
fromfield across paginatedget_messagesresults
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does smstome.com have an official developer API?+
What does `get_messages` return when a phone number has no messages?+
messages array along with count: 0 and total_pages: 0. It does not return an error status. The same behavior applies when you request a page number beyond the available range.How many countries and numbers does the API currently cover?+
list_countries endpoint currently returns 6 countries. Phone numbers are paginated 20 per page via list_phone_numbers. The set of available numbers changes as smstome.com adds or removes temporary numbers.Can I receive real-time push notifications when a new SMS arrives on a number?+
get_messages and search_messages rather than webhooks or streaming. You can fork this API on Parse and revise it to add a polling-based notification layer or webhook dispatcher on top of the existing message endpoints.Does the API expose the full message history for every number?+
get_messages with the page parameter, and search_messages can scan up to max_pages pages of history. However, smstome.com only retains messages for a limited period; older messages may no longer be present on the source. You can fork the API on Parse and revise it to archive retrieved messages to a persistent store before they age out.