DEV Community: William QiBin

International SMS OTP: 4 checks before you ship

William QiBin — Fri, 23 Oct 2026 08:34:40 +0000

Getting an SMS OTP flow working in one market is only the first step. Before launching across countries, I’d check four things: number formatting, message status, retry behavior, and the business funnel.

I work at Chuanglan Yunzhi, a CPaaS company. This is a practical checklist from an employee’s perspective, not an independent vendor comparison. The article was drafted with AI assistance and reviewed by the author.

Normalize numbers, but don’t confuse format with reachability

For APIs that require E.164, a number is generally represented as “+” followed by the country calling code and subscriber number, without punctuation. For example, Twilio’s documentation shows +14155551234 as an E.164-format example.

A valid-looking format does not prove that a number is active or can receive SMS. Keep country/region selection explicit, avoid applying one market’s fixed-length rules globally, and distinguish format validation from actual delivery.

Reference: https://www.twilio.com/docs/phone-numbers/api/incomingphonenumber-resource

Separate “accepted” from “delivered”

An API response may only mean that a request was accepted or queued. In Twilio’s Messages API, for example, “queued” and “delivered” are distinct states. Other providers may use different names or expose different status callbacks, so use the documentation for the service you actually integrate.

For troubleshooting, track three separate stages:

Request accepted: request time, your correlation ID, provider message ID, and error code.

Delivery status: available receipt, its timestamp, and any failure reason.

Business result: whether the user completed OTP verification, how long it took, and how many resend attempts occurred.

A delivery receipt is not proof that a person read the message or completed signup.

Reference: https://www.twilio.com/docs/messaging/api/message-resource

Put retry controls on the backend too

If a message is delayed, users may tap “resend” repeatedly. That can create duplicate messages, extra cost, and abuse risk. A frontend countdown alone is not enough.

Before launch, decide how your backend handles rate limits, duplicate requests, unknown outcomes after a timeout, code expiry, and repeated incorrect attempts. Avoid logging OTP values or full sensitive identifiers in ordinary application logs. Retry limits and backoff should follow your product’s risk and the provider’s documented behavior; one provider’s defaults are not universal.

Reference: https://www.twilio.com/docs/verify/developer-best-practices

Measure the whole signup path

Track the flow as separate events:

OTP requested → request accepted → delivery status available → code verified → signup completed.

When conversion drops, compare the stages before attributing the problem to the SMS route. Test the countries or regions you actually plan to support, using the relevant provider documentation and applicable local requirements.

A short pre-launch review:

1) Are target markets and message use cases defined?
2) Does number handling match the integrated API’s requirements?
3) Can you correlate requests, receipts, and signup outcomes?
4) Are timeout, retry, and rate-limit behaviors explicit?
5) Have local requirements, pricing, and billing terms been checked for each target market?

If you’re evaluating international SMS for an application, you can review Chuanglan’s registration page here:
https://www.chuanglan.com/control/regist?exclusive_code=LKFHZWBU

Disclosure: I work at Chuanglan Yunzhi. The link contains the referral code LKFHZWBU; I have not verified whether it confers any reward or other benefit. Product capabilities, availability, and terms should be confirmed from official materials and your own evaluation.

Your OTP SMS Didn't Fail at Sending — It Failed at Delivery: 4 Checks Developers Miss

William QiBin — Fri, 23 Oct 2026 07:29:01 +0000

Hi, I'm William. I work in CPaaS / A2P messaging, mostly on international SMS delivery for verification, notifications, and alerts.

The most common bug report I hear from developers is:

"The API returned success, but the user never got the code."

That success usually only means the message was accepted. It says almost nothing about whether it was delivered — or delivered in time to matter. For OTP, a code that arrives after 60 seconds is effectively a failed code.

Here are the 4 checks I run first.

1. Route: Is there a direct route to that carrier?

A cheap route is not a cheap message if it never lands.

For international OTP, ask:

Is this a direct carrier connection, or is it hopping through aggregators?
Is the sender ID allowed in the destination country? Many markets reject or rewrite unregistered sender IDs.
Is this route built for OTP traffic, or for bulk marketing traffic? They fail in different ways.

Developer check: Don't test with one number in one country and call it done. Test your top 3 user countries separately. Delivery behaviour is per-country, per-carrier — not global.

2. Speed: Measure delivery time, not send time

Log two timestamps, not one:

t0 = when your system requested the send
t1 = when the delivery receipt (DLR) says "delivered"
delivery_time = t1 - t0

If you only log your API call, you're measuring your own server — not the user's experience.

A practical alert I like:

# Pseudocode: flag slow OTP delivery for investigation
if delivery_time_seconds > 30:
    log_warning("slow_otp_delivery", country=country, carrier=carrier)
if delivery_status != "DELIVERED":
    trigger_fallback()  # voice OTP, another route, or a retry with a new code

3. Receipts: Treat the delivery receipt as part of your product

No DLR handling means you're flying blind. At minimum, handle:

Receipt state	What it usually means	What to do
`DELIVERED`	Handset received it	Stop retrying, mark verification as sent
`UNDELIVERED` / `FAILED`	Carrier or handset rejected it	Check number format, sender ID, and route
`EXPIRED`	Sat too long in transit	Your route is too slow for OTP — change it
No receipt at all	Provider gives you no visibility	That's a provider problem, not a user problem

Wire DLR webhooks into the same dashboard where you watch signup conversion. A sudden drop in delivered rate in one country almost always shows up there before users start complaining.

4. Support: Can a human look at one message ID?

When a single important user can't log in, "check our status page" is not support.

Before you commit to a provider, test this in the trial — not after you sign:

Send a real message.
Give support that one message ID.
See if they can tell you the carrier, the delivery state, and why it failed.

If they can't trace one message, they can't help you debug a country-wide drop either.

A quick pre-launch checklist

[ ] Phone numbers normalised to E.164 (+ + country code) before sending
[ ] Delivery time (not just send time) logged per country
[ ] DLR webhook handled, including EXPIRED and UNDELIVERED
[ ] Fallback ready: second route, voice OTP, or WhatsApp where it makes sense
[ ] One-message trace tested with support using a real message ID

Disclosure: I work at Chuanglan (a CPaaS provider). If you want a sandbox to run the checks above, new accounts currently get 100 free SMS messages + a small API credit to test with: https://www.chuanglan.com/control/regist?exclusive_code=LKFHZWBU — no card needed for the trial. Either way, run the 4 checks on whatever provider you use now. Most "mystery" OTP failures turn out to be check #1 or #3.

What does your OTP failure dashboard look like today — do you track delivery time per country, or just send success rate? I'd genuinely like to compare notes in the comments.