DEV Community

Receive SMS
Receive SMS

Posted on Fully Autonomous

Polling for an SMS code in tests without flakiness: deadlines, intervals and refunds

End-to-end tests that need a real SMS code have one job that is easy to get wrong: waiting. Wait too little and the test fails on a slow carrier. Wait too long and a broken run blocks your pipeline for 15 minutes. Here is the polling pattern we use against a receive-SMS API, with the reasoning behind each number.

The shape of the flow

  1. Buy (or rent) a number for a specific app and country.
  2. Enter it in the sign-up form under test.
  3. Poll for the SMS until it arrives or a deadline passes.
  4. If nothing arrived, cancel the number so you are not charged, and fail the test with a clear message.

The API in these examples is ours (receive-smss.net, base https://receive-smss.net/api/v1, Bearer token), but the pattern works with any provider that has "get number", "read SMS" and "cancel" calls.

Poll with a deadline, not a retry count

Retry counts hide the real budget. Use a monotonic deadline and a fixed interval:

import time, requests

API = "https://receive-smss.net/api/v1"
H = {"Authorization": f"Bearer {API_KEY}"}

def wait_for_code(n_id, deadline_s=300, every_s=5):
    end = time.monotonic() + deadline_s
    while time.monotonic() < end:
        r = requests.get(f"{API}/get_sms", params={"n_id": n_id}, headers=H, timeout=15)
        if r.status_code == 200:
            return r.json()
        if r.status_code != 404:      # 404 just means "no SMS yet"
            r.raise_for_status()
        time.sleep(every_s)
    return None
Enter fullscreen mode Exit fullscreen mode

Why 5 seconds? Most codes arrive within a minute, and polling faster than every few seconds only adds load and rate-limit risk. Why a 5-minute deadline in CI? International SMS sometimes takes several minutes, but if nothing has arrived after five, waiting longer rarely helps in a test. In real user flows we let numbers wait up to 15 minutes; tests should fail faster.

Always clean up

If the deadline passes, cancel the number so the cost is refunded and the number is released:

code = wait_for_code(n_id)
if code is None:
    requests.get(f"{API}/reject_code", params={"n_id": n_id}, headers=H, timeout=15)
    raise AssertionError(f"No SMS for {app}/{country} within 5 minutes")
Enter fullscreen mode Exit fullscreen mode

Put this in a finally block or a test fixture teardown so it also runs when the test crashes halfway.

Pick app and country on evidence

The biggest source of flaky SMS tests is not timing, it is the number type. Some apps barely deliver to shared or virtual ranges. In our data from about 900 free shared numbers (27 Oct to 16 Nov 2026), Telegram delivered 8 codes in 127 tries while Marktplaats in France delivered 45 of 46, and France as a whole did 89% against Mexico's 6%. If your test depends on a third-party app's SMS, use a private number and a country that actually delivers for that app, and keep that choice in config so it is easy to change.

The full per-app, per-country table is public (CC BY 4.0): Kaggle dataset.

Checklist

  • Deadline-based polling, 5 s interval, about 5 min budget in CI.
  • Treat 404 as "not yet", anything else non-200 as an error.
  • Cancel unused numbers in teardown.
  • Log the app, country and number id on failure (never the code itself in public CI logs).
  • Prefer mocks for unit tests; keep real SMS to a small number of end-to-end smoke tests.

Disclosure: I'm part of the team behind receive-smss.net; the API calls shown are ours. The data comes from our own logs.

Top comments (0)