DEV Community: SMSRoute Dev

Send an SMS with one curl (send-only API)

SMSRoute Dev — Sun, 16 Aug 2026 22:32:20 +0000

I work on SMSRoute. This is a disclosed walkthrough of the live send API at sendsmsnokyc.com — not a review, and not a claim about delivery rates.

SMSRoute is send-only. You POST a destination and a body; the API hands the SMS to a carrier. It does not rent numbers, receive OTP, or run a two-way inbox. If you need a number that collects codes, this is the wrong product.

Try it without a key

The homepage has a live test send: Free. No API key required. Rate limited. That is a widget on the site, not the API. Paid sending needs an account.

Account and money

Sign up with email at https://sendsmsnokyc.com/signup/ — no government ID at signup.
Top up at least $5. That is a minimum top-up, not $5 free and not a trial credit.
Pay in crypto. The live /prices list is: BTC, USDT (TRC-20 and ERC-20), ETH, LTC, XMR, SOL. The homepage hero may show fewer coins; use /prices when you document rails.

Docs: https://sendsmsnokyc.com/developers/ · rates: https://sendsmsnokyc.com/prices/

Send

Host: https://api.sendsmsnokyc.com

Method: POST /sms/send

Auth: Authorization: Bearer <api key>

JSON: to, from, body (to in E.164). Use body, not text.

export SMSROUTE_API_KEY=YOUR_API_KEY   # placeholder — put a real key in the env, not in a gist

curl -sS -X POST https://api.sendsmsnokyc.com/sms/send \
  -H "Authorization: Bearer $SMSROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155550123",
    "from": "SMSRoute",
    "body": "Your code is 847291"
  }'

+14155550123 is a documentation number. Swap in a real E.164 destination you are allowed to text.

What this is not

Not inbound / virtual SIM / OTP-receive.
Not "$5 free credits."
No delivery percentage in this post — I am not inventing one.

Sending is the product.

STOP Is Not a String Match: Building an Opt-Out State Machine That Survives Audits

SMSRoute Dev — Thu, 30 Jul 2026 07:34:33 +0000

The one-line implementation and what it misses

Nearly every SMS integration starts here:

if body.strip().upper() == "STOP":
    unsubscribe(sender)

It handles the exact string and nothing else. Real inbound traffic is messier than that in ways that are entirely predictable once you look at a week of logs:

"stop"                    lowercase
"STOP "                   trailing whitespace
"Stop."                   punctuation
"STOP PLEASE"             extra words
"please stop texting me"  keyword not first
"UNSUBSCRIBE"             different keyword
"ARRÊT"                   non-English keyword
"ST0P"                    zero for O

Only the first three are caught by trimming and case-folding. The rest walk straight through, the user keeps receiving messages after asking to stop, and you have both an angry recipient and a compliance problem — carriers act on opt-out complaints, and the consequence lands on your sender reputation before it lands anywhere else.

Normalize, then match on tokens

The fix is a normalization pass followed by token matching rather than whole-string equality.

import re, unicodedata

STOP_WORDS = {"STOP", "STOPALL", "UNSUBSCRIBE", "CANCEL", "END", "QUIT",
              "ARRET", "ARRETER", "ALTO", "PARE"}
START_WORDS = {"START", "YES", "UNSTOP", "SUBSCRIBE"}
HELP_WORDS  = {"HELP", "INFO", "AIDE"}

def normalize(text: str) -> list[str]:
    # strip accents so ARRÊT matches ARRET
    text = unicodedata.normalize("NFKD", text)
    text = "".join(c for c in text if not unicodedata.combining(c))
    text = text.upper()
    # collapse punctuation to spaces, then split
    return [t for t in re.split(r"[^A-Z0-9]+", text) if t]

def classify(text: str) -> str | None:
    tokens = normalize(text)
    if not tokens:
        return None
    # a bare keyword, or a keyword leading the message
    if tokens[0] in STOP_WORDS:
        return "STOP"
    if tokens[0] in START_WORDS:
        return "START"
    if tokens[0] in HELP_WORDS:
        return "HELP"
    # keyword anywhere in a short message: "please stop texting me"
    if len(tokens) <= 5 and STOP_WORDS & set(tokens):
        return "STOP"
    return None

Two deliberate choices are worth naming.

The length guard on the anywhere-match exists to avoid false positives. A long message containing the word "stop" incidentally — "can you stop by the office" — should not unsubscribe anyone. Short messages containing a stop keyword almost always mean it; long ones often do not.

Leetspeak substitutions like ST0P are intentionally not normalized. Mapping digits to letters produces false positives on legitimate content, and the population of users typing a zero deliberately is small. Log unmatched inbound messages and review them periodically rather than guessing at transformations up front — the log tells you what your actual users send, which beats any list you can imagine.

Opt-out is scoped, and the scope is a design decision

"Unsubscribed" is not a single boolean on a user row. The question is always unsubscribed from what, and getting this wrong produces either compliance failures or unnecessary lost reach.

The scope that matters operationally is the sending identity — the long code, short code, or alphanumeric sender ID the user replied to. A user who texts STOP to your marketing sender has not asked to stop receiving login codes from your transactional sender, and suppressing those breaks their account access. Conversely, if you send from a pool of numbers and scope opt-out to the individual number, the next message from a different number in the pool reaches a user who asked you to stop. That is the failure carriers hear about.

A workable model scopes suppression to (recipient, sending_identity) where sending identity is a logical stream rather than a physical number:

CREATE TABLE suppression (
    phone_e164       TEXT        NOT NULL,
    stream           TEXT        NOT NULL,   -- 'marketing', 'transactional', ...
    state            TEXT        NOT NULL,   -- 'opted_out' | 'opted_in'
    changed_at       TIMESTAMPTZ NOT NULL,
    source           TEXT        NOT NULL,   -- 'inbound_sms' | 'api' | 'support'
    inbound_message  TEXT,                   -- verbatim text that caused it
    PRIMARY KEY (phone_e164, stream)
);

CREATE TABLE suppression_log (   -- append-only history, never updated
    id               BIGSERIAL PRIMARY KEY,
    phone_e164       TEXT        NOT NULL,
    stream           TEXT        NOT NULL,
    state            TEXT        NOT NULL,
    changed_at       TIMESTAMPTZ NOT NULL,
    source           TEXT        NOT NULL,
    inbound_message  TEXT
);

The current-state table answers "may I send to this number right now" with a single indexed lookup on the send path. The append-only log answers "prove this user consented on that date", which is the question that actually gets asked when a complaint arrives. Do not try to serve both from one mutable table; the moment you update a row you have destroyed the evidence.

Store the verbatim inbound text. When a dispute lands months later, "the user sent STOP" is an assertion, whereas the stored message is evidence.

The race that silently re-subscribes people

This is the bug that survives a correct keyword matcher and a correct data model.

Opt-out arrives as an inbound webhook. Campaign sends are dispatched from a queue. Between the moment a message is enqueued and the moment it is handed to the carrier, an opt-out can land. If the suppression check happens at enqueue time only, every message already in the queue goes out after the user asked you to stop.

For a large campaign the queue can hold minutes of work. A user who replies STOP to the first message keeps receiving the remainder.

# WRONG: checked once, at enqueue
for phone in audience:
    if not suppressed(phone, stream):
        queue.push(build(phone))       # opt-out after this point is ignored

The check must happen immediately before dispatch, not only at enqueue:

# enqueue-time check is still worth doing — it avoids queueing obvious no-ops
for phone in audience:
    if not suppressed(phone, stream):
        queue.push(build(phone))

# but the authoritative check is at send time
def dispatch(job):
    if suppressed(job.phone, job.stream):       # re-check, always
        record_skipped(job, reason="suppressed_after_enqueue")
        return
    provider.send(job)

Recording the skip rather than dropping silently matters. "We suppressed 1,240 messages mid-campaign because those users opted out" is a defensible operational story; an unexplained gap between audience size and messages sent is not.

The same reasoning applies to any scheduling delay. A message scheduled for tomorrow must be checked against tomorrow's suppression state, not today's.

Confirmations, and the loop to avoid

Regulators and carriers generally expect a single confirmation message acknowledging the opt-out, after which you send nothing further on that stream. Two constraints follow.

The confirmation must bypass the suppression check, because the user is now suppressed and a naive implementation will suppress the confirmation itself. Mark it explicitly:

def on_stop(phone, stream, raw_text):
    set_state(phone, stream, "opted_out", source="inbound_sms", inbound=raw_text)
    send(phone, CONFIRMATION_TEXT, stream=stream, bypass_suppression=True)

And exactly one confirmation, ever. If a user sends STOP three times and you reply three times, you have sent two messages to someone who asked you to stop. Send the confirmation only on an actual state transition — when the row moved from opted-in to opted-out — not on every inbound STOP. If they were already suppressed, record the inbound message and stay silent.

That distinction is easy to encode: perform the state write conditionally and send only if it changed a row.

START must be as reliable as STOP

Opt-in reversal gets a fraction of the attention and produces support tickets that are hard to diagnose, because the user is certain they fixed it and your system disagrees.

Treat START symmetrically: same normalization, same token matching, same scoping, same append-only log entry, same single confirmation on transition. The one asymmetry worth keeping is direction of doubt. When classification is ambiguous, resolve toward suppression — an unnecessary opt-out costs you one recipient, while a missed opt-out costs sender reputation and potentially a carrier complaint.

What an audit actually asks for

The questions that arrive during a complaint investigation are narrower and more concrete than most teams expect:

For this number, what is the current state on this stream, and when did it change?
What was the verbatim inbound message that caused the change?
Show every message sent to this number after that timestamp.
If any were sent, why — which code path bypassed suppression, and was that legitimate?

Every one of these is answerable in seconds if you kept the append-only log with verbatim text and recorded suppression skips. None are answerable from a mutable boolean column, and reconstructing them from application logs after the fact is painful and unconvincing.

Handling of inbound keywords also differs by provider — some intercept STOP at the platform level and never deliver it to your webhook, others pass everything through and expect you to act. Those two worlds require different code, and assuming the wrong one means either double-handling or no handling at all. Confirm which model your gateway uses before you build; whichever SMS gateway you integrate should document whether keywords are intercepted upstream or delivered to you.

Summary

Normalize (strip accents, fold case, split on punctuation) then match tokens; do not compare whole strings.
Guard anywhere-in-message matching with a length limit to avoid false positives.
Scope suppression to (number, logical stream), not to a global boolean or a physical number.
Keep a mutable current-state table for the send path and an append-only log for evidence.
Re-check suppression immediately before dispatch, not only at enqueue, and record every skip.
Send exactly one confirmation, on state transition only, bypassing suppression.
Make START as robust as STOP, but resolve ambiguity toward suppression.

Your Inbound SMS Webhook Is a Public Endpoint: HMAC Verification, Replay, and Out-of-Order Delivery

SMSRoute Dev — Thu, 30 Jul 2026 07:28:47 +0000

The endpoint you forgot is on the internet

Inbound SMS and delivery-status callbacks arrive as HTTP POSTs to a URL you registered with your provider. That URL is reachable by anyone who guesses or discovers it. It is not protected by your session middleware, it usually sits outside your authenticated API surface, and in most codebases it is the one route with the least scrutiny.

A representative unprotected handler:

@app.post("/webhooks/sms")
def inbound():
    payload = request.json
    if payload["text"].strip().upper() == "STOP":
        suppress(payload["from"])
    return "", 200

Anyone who can reach this can suppress any number in your database by POSTing a forged payload. No credentials required. The same pattern applied to a status callback lets an attacker mark messages delivered that never arrived, or trigger your retry path for messages that did.

Three defects need fixing, and they are independent: the payload is unauthenticated, a captured request can be replayed indefinitely, and callbacks do not arrive in the order the events happened.

Verifying the signature

Providers sign webhook bodies with a shared secret, typically HMAC-SHA256 over the raw request body, sometimes with the timestamp or URL prefixed. The header name varies; the mechanism rarely does.

Four things go wrong in implementations, and the first two are subtle enough to pass every test you are likely to write.

Comparing with ==. String equality short-circuits on the first differing byte, so comparison time leaks how many leading bytes were correct. That is a practical oracle for forging a signature byte by byte over many requests. Use a constant-time comparison.

Signing the parsed body instead of the raw bytes. If you verify against a re-serialized version of the parsed JSON, any difference in key order, whitespace, or unicode escaping produces a different digest. Worse, some frameworks let you re-serialize into a form that matches while the original bytes contained something else entirely. Capture the raw body before parsing.

import hmac, hashlib, time

MAX_SKEW = 300  # seconds

def verify(raw_body: bytes, header_sig: str, header_ts: str, secret: bytes) -> bool:
    # 1. reject stale or future-dated requests before doing any work
    try:
        ts = int(header_ts)
    except (TypeError, ValueError):
        return False
    if abs(time.time() - ts) > MAX_SKEW:
        return False

    # 2. sign exactly what the provider signed: timestamp + raw bytes
    signed = f"{ts}.".encode() + raw_body
    expected = hmac.new(secret, signed, hashlib.sha256).hexdigest()

    # 3. constant-time comparison
    return hmac.compare_digest(expected, header_sig or "")

In Flask the raw body is request.get_data(); in Express you need express.raw({type: '*/*'}) on that route specifically, because express.json() consumes the stream and leaves you unable to recover the original bytes.

Verifying after parsing. If your JSON parser runs before verification, you have handed unauthenticated input to a parser. Verify first, parse second.

Falling open on a missing header. if sig and not verify(...) skips verification entirely when the header is absent, which is exactly the request an attacker sends. Treat a missing signature as a failed signature.

The timestamp window does not stop replay

A valid signed request stays valid for as long as your skew window allows. If an attacker captures one — from a log aggregator, an error report, a proxy, a misconfigured APM trace — they can resend it verbatim, and it will verify correctly every time within those five minutes.

For an inbound STOP that is a nuisance. For a status callback that advances a state machine or triggers billing, it is a real problem.

The fix is to make each delivery single-use. Providers send a unique event or message identifier; record the ones you have processed and reject repeats.

REPLAY_TTL = 600   # must exceed MAX_SKEW, with margin

def claim_once(event_id: str) -> bool:
    """True the first time this event_id is seen, False on every repeat."""
    # SET NX is atomic: no check-then-act race between concurrent deliveries
    return bool(redis.set(f"wh:{event_id}", "1", nx=True, ex=REPLAY_TTL))

@app.post("/webhooks/sms")
def inbound():
    raw = request.get_data()
    if not verify(raw, request.headers.get("X-Signature"),
                  request.headers.get("X-Timestamp"), SECRET):
        return "", 403
    event = json.loads(raw)
    if not claim_once(event["id"]):
        return "", 200          # already handled; acknowledge, do not reprocess
    process(event)
    return "", 200

Two details matter. The TTL must be longer than the skew window, or a request can expire from the replay cache while its signature is still valid. And the claim must be atomic — a GET followed by a SET has a window where two concurrent deliveries of the same event both see "not present" and both process. SET NX collapses that to one winner.

Note that returning 200 for a duplicate is correct. The provider is telling you about an event; you have already recorded it. Returning an error would trigger their retry logic for something you handled successfully.

Callbacks arrive out of order, and the fix is not a queue

This is the failure that survives every security control above, because nothing is forged — the messages are genuine, they simply arrive in the wrong sequence.

A message's lifecycle produces several callbacks: accepted, sent, delivered. These are independent HTTP requests, frequently from different workers on the provider's side, traversing different network paths, subject to independent retries. There is no ordering guarantee. delivered overtaking sent is routine, not exotic.

The naive handler corrupts state on every reorder:

def on_status(event):
    db.execute("UPDATE messages SET status = ? WHERE id = ?",
               (event["status"], event["message_id"]))   # last writer wins

If delivered arrives and then a delayed sent lands behind it, the message reverts to sent and stays there. Your dashboard under-reports delivery, and any logic keyed on the terminal state — billing, retries, user notification — misfires.

Ordering by timestamp helps but does not close it, because provider clocks are not synchronized across workers and events can share a timestamp. The robust approach is to encode the state machine's own ordering and refuse backward transitions:

RANK = {"queued": 0, "accepted": 1, "sent": 2, "delivered": 3,
        "failed": 3, "undelivered": 3}   # terminal states share the top rank

def on_status(event):
    new = event["status"]
    db.execute(
        """UPDATE messages
              SET status = ?, status_rank = ?, updated_at = ?
            WHERE id = ?
              AND status_rank < ?""",          # monotonic: never move backward
        (new, RANK[new], event["timestamp"], event["message_id"], RANK[new]))

The WHERE status_rank < ? clause makes the update idempotent and order-independent. A late sent simply matches no rows and is discarded. The database enforces monotonicity, so concurrent handlers cannot interleave into a bad state.

Terminal states need care: delivered and failed share a rank, so whichever arrives first wins and the other is dropped. That is usually what you want, since a message cannot be both. If your provider can legitimately send delivered after a transient failed, give the terminal states distinct ranks reflecting the true precedence.

Responding correctly

Your response controls the provider's retry behaviour, and getting it wrong causes either duplicate processing or silent loss.

Acknowledge fast, then process. Most providers time out webhook calls in the low single-digit seconds and treat a timeout as failure, retrying the delivery. If your handler does the work inline and takes longer than that window, you receive the same event repeatedly, each attempt doing the work again. Write the event to a queue, return 200, and process asynchronously.

Return 2xx only when you have durably accepted the event — after the queue write commits, not before. Return 5xx when you want a retry, such as your datastore being unavailable. Return 4xx for a permanently unprocessable event, such as a failed signature, since retrying will not help.

The mapping to avoid is returning 200 on an internal error to "stop the noise". The provider treats that as success, does not retry, and the event is gone.

A checklist worth running against your handler

Signature verified against the raw body, before parsing.
Comparison uses hmac.compare_digest or the equivalent, never ==.
Missing signature header rejects, rather than skipping verification.
Timestamp skew window enforced, and the replay TTL exceeds it.
Replay claim is atomic (SET NX), not check-then-set.
Status updates are monotonic by rank, so reordered callbacks cannot regress state.
Handler acknowledges within the provider's timeout and processes asynchronously.
2xx only after durable acceptance; 5xx to request retry; 4xx for unprocessable.

Provider signing schemes differ in what exactly is signed — body only, timestamp plus body, or URL plus timestamp plus body — so verify against your gateway's published scheme rather than assuming. If you are evaluating gateways, the webhook signing and idempotency documentation is worth reading before the integration rather than after; whichever SMS API you use should state its signing construction explicitly.

The handler is the smallest file in your codebase and the only one an unauthenticated stranger can reach. Give it the scrutiny that implies.

Your SMPP Bind Is Idle 90% of the Time: Window Size, RTT, and the Throughput Math

SMSRoute Dev — Thu, 30 Jul 2026 07:28:11 +0000

The complaint: "we bought 100 TPS and we're getting 12"

An operator provisions a bind rated at 100 messages/second. Production measures 12. Nobody has touched the carrier config, and the provider's dashboard shows no throttling errors — no ESME_RTHROTTLED, no queue backlog on their side.

The bug is not the carrier. It is a client that sends one submit_sm and waits for the matching submit_sm_resp before sending the next.

That design has a hard ceiling that has nothing to do with what you purchased:

max_throughput = window_size / round_trip_time

With a window of 1 and an 80 ms RTT to the SMSC:

1 / 0.080s = 12.5 messages/second

Twelve. Exactly what was measured. The bind spends roughly 90% of every second waiting on network latency with zero bytes in flight. You cannot buy your way out of this; 1000 TPS of entitlement divided by a window of 1 is still 12.5.

What "window" actually means in SMPP

SMPP v3.4 is an asynchronous protocol running over a single TCP connection. Every PDU carries a sequence_number, and responses reference the sequence number of the request they answer. Nothing in the specification requires you to wait for a response before sending the next request.

The window is simply how many PDUs you allow to be outstanding — sent, not yet acknowledged — at any moment. It is a client-side choice, enforced by your own bookkeeping. Most naive clients set it to 1 implicitly by writing synchronous code:

# implicit window = 1: the ceiling is 1/RTT, forever
for msg in queue:
    sock.send(encode_submit_sm(msg, seq=next_seq()))
    resp = read_pdu(sock)          # <-- blocks here, link goes idle
    handle(resp)

The asynchronous form decouples sending from acknowledgement:

# window = N: up to N PDUs in flight
inflight = {}                       # sequence_number -> (msg, sent_at)
while queue or inflight:
    while queue and len(inflight) < WINDOW:
        msg = queue.popleft()
        seq = next_seq()
        inflight[seq] = (msg, now())
        sock.send(encode_submit_sm(msg, seq=seq))
    pdu = read_pdu(sock)            # responses arrive out of order
    if pdu.command_id == SUBMIT_SM_RESP:
        msg, sent_at = inflight.pop(pdu.sequence_number, (None, None))
        if msg is None:
            log.warning("resp for unknown seq %d", pdu.sequence_number)
        else:
            observe_rtt(now() - sent_at)
            handle(msg, pdu)

With a window of 20 and the same 80 ms RTT:

20 / 0.080s = 250 messages/second

Now the carrier's 100 TPS limit is the binding constraint, which is what you paid for.

Choosing a window size without guessing

The useful heuristic is Little's Law. To sustain a target rate you need enough messages in flight to cover one round trip:

window >= target_tps * rtt_seconds

For 100 TPS at 80 ms:

100 * 0.080 = 8      # minimum

Set it somewhat above the minimum to absorb RTT jitter — a window of 16 to 32 is a reasonable operating range for most binds. Going far higher does not help: once the carrier's rate limit is the bottleneck, extra window depth only converts into queueing delay and larger loss on reconnect.

Two constraints bound it from above:

The SMSC has its own window. Many SMSCs cap outstanding PDUs per bind, commonly in the 10 to 100 range. Exceeding it does not fail cleanly — some implementations stop reading, and TCP backpressure stalls your writes. Ask the carrier for the number rather than probing for it in production.

Everything in flight is at risk on disconnect. A window of 500 means 500 messages whose fate is unknown when the socket drops. Each one is a message you must either re-submit, and possibly duplicate, or drop. Window size is therefore also a decision about how much ambiguity you are willing to resolve after a failure.

The sequence_number bug that silently drops messages

sequence_number is a 4-byte field, but SMPP restricts valid values to 0x00000001 through 0x7FFFFFFF. Two errors are common and both are quiet.

The first is starting at zero or letting the counter run past the maximum into negative territory in languages with signed integers. The second is reusing a number that is still in flight.

Reuse is the dangerous one. If sequence 42 is outstanding and you assign 42 to a second message, the next submit_sm_resp with sequence 42 is ambiguous. Your correlation map holds one entry, so one message gets the response and the other is orphaned. It is never acknowledged, never retried, and never reported as failed. It simply vanishes, and the only symptom is a delivery rate slightly below what your own counters claim.

Correct generation wraps within the legal range and skips values still in use:

MAX_SEQ = 0x7FFFFFFF

def next_seq(self):
    for _ in range(MAX_SEQ):
        self._seq = self._seq + 1 if self._seq < MAX_SEQ else 1
        if self._seq not in self.inflight:
            return self._seq
    raise RuntimeError("sequence space exhausted: inflight window is too large")

If that loop ever exhausts, your window is larger than the sequence space, which means it is far larger than it should be.

enquire_link: the keepalive that decides how fast you notice death

A TCP connection to an SMSC can be dead for minutes without either side noticing. NAT devices and stateful firewalls drop idle mappings silently; no FIN, no RST. Your socket remains ESTABLISHED in the kernel while writes disappear.

enquire_link is SMPP's application-level keepalive. Send it on an interval, expect enquire_link_resp within a timeout, and tear the bind down when the response does not arrive.

ENQUIRE_INTERVAL = 30      # seconds between keepalives
ENQUIRE_TIMEOUT  = 10      # give up on a response after this

if now() - last_pdu_sent > ENQUIRE_INTERVAL:
    seq = next_seq()
    send_enquire_link(seq)
    pending_enquire[seq] = now()

for seq, sent_at in list(pending_enquire.items()):
    if now() - sent_at > ENQUIRE_TIMEOUT:
        log.error("enquire_link %d timed out; rebinding", seq)
        reconnect()
        break

The interval is a tradeoff against NAT idle timeouts, which frequently sit between 60 and 300 seconds. Thirty seconds is comfortably inside typical windows. Pushing to 300 seconds risks the mapping expiring before your keepalive refreshes it, at which point you discover the dead link only when a real message fails.

Note the ordering that matters: detection time is ENQUIRE_INTERVAL + ENQUIRE_TIMEOUT in the worst case, and every message submitted during that window is in doubt.

Reconnect: the part that creates duplicates

When a bind drops with a non-empty window, each in-flight message is in one of three states, and the client cannot distinguish them:

Never reached the SMSC. Safe to resubmit.
Reached the SMSC and was accepted; the response was lost. Resubmitting sends the message twice.
Reached the SMSC and was rejected; the response was lost. Resubmitting is correct.

There is no SMPP mechanism that resolves this ambiguity for you. The protocol gives you no way to ask "did you already accept sequence 42?" — and after a rebind, sequence numbers restart anyway.

The practical resolution is to move the deduplication key up a layer. Attach your own message identifier to each send, keep a short-lived record of identifiers submitted in the last few minutes, and check it before resubmitting after a reconnect. If your platform exposes an idempotency key on send, that mechanism is what it exists for. Providers differ in whether they offer one, so this is worth confirming against your gateway's API documentation before you need it — the SMS API docs for whichever gateway you use should state whether repeated submissions with the same key collapse to one message.

Without a dedup layer, the safe options are both bad: resubmit and accept duplicate OTPs, or drop and accept silent loss. Pick deliberately rather than by default.

Measuring the right thing

Three metrics tell you whether the bind is healthy, and none of them is "messages sent".

Window occupancy — the average size of your in-flight map. If it sits near zero, your window is not the constraint and something upstream is starving the sender. If it pins at the maximum, the window is the constraint and you should raise it or accept the ceiling.

RTT percentiles — measured from send to matching response, not from your queue. The p50 tells you what window size you need; the p99 tells you how much jitter headroom to add. A p99 that is many multiples of p50 usually indicates SMSC-side queueing, and raising your window will not fix it.

Unmatched responses — responses arriving for sequence numbers not in your map. This should be exactly zero. Any nonzero value means either sequence reuse or a correlation bug, and both cause silent message loss.

A bind that reports high throughput and a nonzero unmatched-response count is not delivering what its counters claim.

The short version

One submit_sm at a time caps throughput at 1/RTT, independent of what the carrier sold you.
Size the window as target_tps * rtt, then add headroom for jitter; confirm the SMSC's own cap rather than probing it.
Generate sequence_number within 1..0x7FFFFFFF and never reuse a value still in flight, or messages disappear without error.
Send enquire_link well inside NAT idle timeouts; worst-case detection is interval plus timeout.
Everything in the window is ambiguous when the link drops. Deduplicate above SMPP or choose which failure mode you prefer.

Parsing Phone Numbers Is Harder Than Parsing Dates: E.164, libphonenumber, and the Inputs That Break You

SMSRoute Dev — Thu, 30 Jul 2026 07:20:38 +0000

One user, five spellings

Support opened a ticket: a user could not log in because "that phone number is already registered." The account in the database had 0171 5550134. The form submission had +49 171 5550134. Same German mobile. Two rows. The unique index on phone did nothing useful because we stored whatever the user typed.

That same number shows up in the wild as:

0171 5550134 (national, trunk prefix)
+491715550134 (E.164-ish, no spaces)
00491715550134 (international exit code)
49 (0) 171 5550134 (country code plus explicit trunk)
+49.171.555.0134 (punctuation cosplay)

If you persist the raw string, uniqueness is fiction, OTP dedupe keys fragment, and "send code to the number on file" becomes a coin flip. You need one canonical form at the boundary, every time.

E.164 in one paragraph, honestly

E.164 is the ITU recommendation for the international public telecommunication numbering plan. The shape is simple: a leading +, then a country code (1–3 digits), then the subscriber number, for a maximum of 15 digits total after the +. No spaces, dashes, parentheses, or dots. +491715550134 is E.164. +49 171 5550134 is not. What E.164 does not tell you: whether the number is assigned, whether it is mobile, whether it can receive SMS, or whether it will ring. It is a formatting and addressing contract, not a reachability oracle. libphonenumber will not fill that gap either — it checks structure against national numbering plans, not live carrier state.

Never regex this: use libphonenumber

Google's libphonenumber (and its ports) encodes the numbering plans you will not keep current by hand. Parse with an explicit default region when the input lacks a + country code; format to E.164 for storage.

Python (phonenumbers):

import phonenumbers
from phonenumbers import NumberParseException

def to_e164(raw: str, default_region: str = "DE") -> str | None:
    try:
        num = phonenumbers.parse(raw, default_region)
    except NumberParseException:
        return None
    if not phonenumbers.is_valid_number(num):
        return None
    return phonenumbers.format_number(
        num, phonenumbers.PhoneNumberFormat.E164
    )

print(to_e164("0171 5550134", "DE"))   # +491715550134
print(to_e164("+49 171 5550134", "DE")) # +491715550134
print(to_e164("00491715550134", "DE"))  # +491715550134

JavaScript (libphonenumber-js):

import { parsePhoneNumberFromString } from 'libphonenumber-js';

function toE164(raw, defaultCountry = 'DE') {
  const num = parsePhoneNumberFromString(raw, defaultCountry);
  if (!num || !num.isValid()) return null;
  return num.format('E.164');
}

console.log(toE164('0171 5550134', 'DE'));   // +491715550134
console.log(toE164('+49 171 5550134', 'DE')); // +491715550134
console.log(toE164('00491715550134', 'DE'));  // +491715550134

Two predicates matter and they are not interchangeable:

is_valid_number / isValid() — the number is possible and matches a known length/pattern for that region. Use this on signup and OTP forms.
is_possible_number / isPossible() — length only, against broad regional bounds. Use this when ingesting legacy CRM dumps where you would rather keep a maybe-number than drop the row.

Form validation wants valid. Bulk migration of ten-year-old CSV wants possible, plus a report of everything that failed even that bar. Do not ship a "phone validation regex." National plans change; your one-liner will not.

The gotcha gallery

These are numbers that hand-rolled normalizers mangle. Each line is input → wrong output you might emit → correct E.164.

Argentina mobiles insert a 9 after the country code for international dialing (and SMS gateways expect it).

Input: 11 2345-6789 with region AR (Buenos Aires mobile, national form).

Wrong: +541123456789 (missing the mobile 9).

Correct: +5491123456789.

libphonenumber's AR rules add the 9 when the number is typed as mobile; a strip-non-digits routine will not.

Mexico dropped the trunk 1 after country code 52 for mobiles in 2019.

Input (legacy stored value): +5215512345678.

Wrong if you "trust stored E.164 forever": keep +5215512345678 and watch modern routes reject or misroute it.

Correct today: +525512345678.

Re-parse legacy rows; do not assume yesterday's E.164 string is still the dialable form.

UK numbers written with an explicit trunk zero inside parentheses.

Input: +44 (0)7911 123456.

Wrong: +4407911123456 (naively deleting punctuation but keeping the 0).

Correct: +447911123456.

The (0) is a national trunk prefix reminder for domestic dialing; it must not appear after +44.

Trunk-prefix 0 means different things by country.

German input 0171 5550134 → correct +491715550134 (drop the leading 0 after applying country code 49).

Italian landline input 06 12345678 (Rome) → correct +390612345678 (the leading 0 is significant and stays part of the national number).

Wrong generic rule "always strip one leading zero after the country code" produces +39612345678 for the Italian case — a different, invalid number. Region-aware parse is the only safe path.

Italian landlines keep the leading zero; mobiles do not share the same shape.

Input: 02 1234567 region IT.

Wrong (strip-all-leading-zeros policy): +3921234567.

Correct: +39021234567.

If your normalizer is a pair of regex replacements, you will get this wrong for at least one of DE/IT/AT/CH on day one.

Leading zeros, spreadsheets, and other data-loss machines

Phone numbers are not integers. Store them as integers and you lose the leading +, every leading zero, and any chance of round-tripping national forms. A column typed as BIGINT turns +491715550134 into 491715550134 and 01632 960775 into 1632960775 — both irreversible without guessing the region.

CSV is worse when Excel touches it. Open a export containing +447911123456, save, re-upload: you get 4.47911E+11 or 447911123456. The + is gone. Leading zeros on national numbers are gone. Downstream parse then guesses wrong region or fails is_valid_number.

Rules that survive contact with finance teams:

Column type TEXT / VARCHAR (at least 16 chars for E.164, more if you also keep a display field).
Always persist the canonical value with the leading +.
Quote the field in CSV ("+447911123456") and prefer .xlsx with an explicit text column when non-engineers will open the file.
Never cast through numeric types in ETL "for cleanup."

Validation UX that doesn't lose signups

Canonical storage is a backend concern. The form still has to accept how humans type.

Put a country selector next to the input. That selection is the default_region / defaultCountry you pass to parse. Do not infer country only from Accept-Language or IP; roaming users exist.
Run AsYouTypeFormatter (Python: phonenumbers.AsYouTypeFormatter; JS: AsYouType from libphonenumber-js) on input so 0171555… becomes a readable national pattern for the chosen country while the user types.
Validate on blur, not on every keystroke with a hard error. Empty-while-typing is not an error.
On failure, show the expected national example for that country (phonenumbers.example_number_for_type(region, PhoneNumberType.MOBILE) / getExampleNumber), not a generic "invalid phone."
Never block paste. Users paste from contacts, WhatsApp, and email signatures. Strip formatting on paste, then re-run the as-you-type formatter; do not preventDefault on paste.

Sketch for the blur path in JS:

import parsePhoneNumberFromString, { AsYouType } from 'libphonenumber-js';

const input = document.querySelector('#phone');
const country = () => document.querySelector('#country').value;

input.addEventListener('input', () => {
  const formatter = new AsYouType(country());
  input.value = formatter.input(input.value);
});

input.addEventListener('blur', () => {
  const num = parsePhoneNumberFromString(input.value, country());
  if (!num || !num.isValid()) {
    input.setCustomValidity(
      `Use a valid number for ${country()}, e.g. the national format for that country.`
    );
  } else {
    input.setCustomValidity('');
    // send num.format('E.164') to the API
  }
});

The API accepts only E.164. The client may show national format. Those are different layers; do not store what the input visually contains at submit time without parsing first.

Type detection and what it's worth

libphonenumber can classify a parsed number:

import phonenumbers
from phonenumbers import phonenumberutil

num = phonenumbers.parse("+491715550134", None)
print(phonenumberutil.number_type(num))
# PhoneNumberType.MOBILE

import { parsePhoneNumberFromString } from 'libphonenumber-js';

const num = parsePhoneNumberFromString('+491715550134');
console.log(num.getType()); // 'MOBILE'

Useful values: MOBILE, FIXED_LINE, FIXED_LINE_OR_MOBILE, VOIP, TOLL_FREE, and a handful of others. Practical use: a soft signal before you fire an OTP SMS — if the type is clearly FIXED_LINE or TOLL_FREE in a region where that distinction is reliable, warn the user and offer voice call instead of silently failing delivery.

Unreliable cases you must not hard-block on:

United States and Canada: huge slices land in FIXED_LINE_OR_MOBILE because the plan does not cleanly separate them; number portability makes yesterday's landline a mobile.
Ported numbers anywhere: the library's type is plan metadata, not current carrier assignment.
VOIP and virtual ranges: often valid, sometimes SMS-capable, sometimes not — structure alone cannot decide.

libphonenumber does not verify reachability. It has never claimed to. Treat number_type as a UX hint, not an authorization gate. In practice I normalize to E.164 at the edge and let the SMS API I send through reject the truly undeliverable ones, logging its per-number error codes rather than trying to pre-guess carrier reachability myself.

The storage and comparison contract

Contract:

Store a single E.164 string (TEXT, including +).
Compare E.164 strings only (a.phone = b.phone, hash sets of E.164 for OTP cooldown keys).
Display at the edge with national or international formatting — never re-format on the way into the database.

import phonenumbers
from phonenumbers import PhoneNumberFormat, NumberParseException

def display_national(e164: str) -> str:
    num = phonenumbers.parse(e164, None)
    return phonenumbers.format_number(num, PhoneNumberFormat.NATIONAL)

Migration for a table already full of free-text junk: parse, write E.164 into a new column, and report failures instead of deleting rows.

import csv
import phonenumbers
from phonenumbers import PhoneNumberFormat, NumberParseException

def migrate_row(raw: str, default_region: str) -> tuple[str | None, str | None]:
    """Returns (e164, error_reason)."""
    if raw is None or not str(raw).strip():
        return None, "empty"
    try:
        num = phonenumbers.parse(str(raw).strip(), default_region)
    except NumberParseException as e:
        return None, f"parse: {e.error_type.name}"
    if not phonenumbers.is_possible_number(num):
        return None, "not_possible"
    # Prefer valid; still keep possibles for manual review
    e164 = phonenumbers.format_number(num, PhoneNumberFormat.E164)
    if not phonenumbers.is_valid_number(num):
        return e164, "possible_but_not_valid"
    return e164, None

# Example batch with a side-car report
report_path = "phone_migration_report.csv"
with open(report_path, "w", newline="", encoding="utf-8") as report:
    writer = csv.writer(report)
    writer.writerow(["id", "raw", "e164", "status"])
    for row_id, raw, region in load_legacy_rows():  # your DB cursor
        e164, err = migrate_row(raw, region or "US")
        if err == "possible_but_not_valid":
            writer.writerow([row_id, raw, e164, err])
            save_e164(row_id, e164)  # keep, flag for review
        elif err:
            writer.writerow([row_id, raw, "", err])
            # do not save — leave old value, page a human
        else:
            writer.writerow([row_id, raw, e164, "ok"])
            save_e164(row_id, e164)

Unparseable rows stay in the report with a reason (EMPTY, INVALID_COUNTRY_CODE, NOT_A_NUMBER, TOO_SHORT_NSN, TOO_LONG — those names are the NumberParseException error types). Silent drops create support tickets you cannot reconstruct.

Checklist

[ ] Parse with libphonenumber (or port), never a hand-rolled regex
[ ] Pass an explicit default region when input lacks +
[ ] Persist E.164 only (TEXT/VARCHAR, leading + kept)
[ ] Uniqueness, OTP cooldown, and account lookup keys use the E.164 string
[ ] Forms: country selector → region; AsYouType on input; validate on blur; paste allowed
[ ] is_valid_number on interactive signup; is_possible_number only for legacy ingest
[ ] number_type is a soft warning before SMS, not a hard block
[ ] Do not expect libphonenumber to confirm deliverability or carrier
[ ] Argentina mobiles: expect +54 9 …; Mexico: re-parse pre-2019 +521… values
[ ] UK +44 (0)… drops the trunk 0; Italian landlines keep their leading 0
[ ] Migrate free-text columns with a failure report, not UPDATE … WHERE parsed IS NULL deletes
[ ] Format national/international only in UI or notification templates

Someone Is Draining Your SMS Budget: Rate-Limiting OTP Endpoints Against Enumeration and SMS Pumping

SMSRoute Dev — Thu, 30 Jul 2026 07:13:45 +0000

The attack you find on your invoice

Finance forwarded a carrier invoice triple the usual size. The SMS provider dashboard showed a clean spike starting 02:14 UTC. Application logs told the rest: thousands of POST /v1/auth/otp/send calls, each body a different MSISDN, almost no follow-up POST /v1/auth/otp/verify.

The numbers themselves were the signature. Sorted, they looked like this:

+251911000001
+251911000002
+251911000003
+251911000004
...

One request per number. No retries on the same MSISDN. Zero verify attempts against any of them. That pattern is SMS pumping: a bot feeds premium-route destinations into an unauthenticated (or weakly authenticated) "send code" endpoint. The terminating network shares revenue on those messages; the attacker and the terminating party split the inflated traffic. Your budget is the third party in that arrangement.

If your send endpoint accepts any E.164 string and immediately hands it to the provider, you are the open hose.

Layer 1 — per-destination throttling with a real algorithm

Cap how often any single destination can receive a code. A token bucket works: capacity 1, refill one token every 60 seconds, plus a hard daily ceiling so a patient bot cannot drip forever.

Naive GET then SET is racy under concurrency — two requests read tokens=1, both decrement, both send. Use an atomic path. Redis Lua is the portable one:

import redis
import time

r = redis.Redis(host="localhost", port=6379, decode_responses=True)

# KEYS[1] = bucket key for this MSISDN
# ARGV[1] = now (ms), ARGV[2] = capacity, ARGV[3] = refill_ms
# ARGV[4] = daily key, ARGV[5] = daily_cap, ARGV[6] = day_ttl_sec
TOKEN_BUCKET_LUA = """
local key = KEYS[1]
local now = tonumber(ARGV[1])
local capacity = tonumber(ARGV[2])
local refill_ms = tonumber(ARGV[3])
local day_key = ARGV[4]
local day_cap = tonumber(ARGV[5])
local day_ttl = tonumber(ARGV[6])

local day_count = tonumber(redis.call('GET', day_key) or '0')
if day_count >= day_cap then
  return {0, -1, day_count}
end

local data = redis.call('HMGET', key, 'tokens', 'ts')
local tokens = tonumber(data[1])
local ts = tonumber(data[2])

if tokens == nil then
  tokens = capacity
  ts = now
end

local elapsed = math.max(0, now - ts)
local refill = math.floor(elapsed / refill_ms)
tokens = math.min(capacity, tokens + refill)
if refill > 0 then
  ts = ts + refill * refill_ms
end

if tokens < 1 then
  local wait = refill_ms - (now - ts)
  return {0, wait, day_count}
end

tokens = tokens - 1
redis.call('HMSET', key, 'tokens', tokens, 'ts', ts)
redis.call('PEXPIRE', key, capacity * refill_ms * 2)

day_count = redis.call('INCR', day_key)
if day_count == 1 then
  redis.call('EXPIRE', day_key, day_ttl)
end

return {1, 0, day_count}
"""

token_bucket = r.register_script(TOKEN_BUCKET_LUA)

def allow_send(msisdn: str) -> tuple[bool, int]:
    now_ms = int(time.time() * 1000)
    day_key = f"otp:day:{time.strftime('%Y%m%d')}:{msisdn}"
    allowed, wait_ms, _ = token_bucket(
        keys=[f"otp:bucket:{msisdn}"],
        args=[now_ms, 1, 60_000, day_key, 5, 90_000],
    )
    return bool(allowed), int(wait_ms)

Call allow_send before you touch the provider. On allowed=False, return 429 and do not enqueue an SMS. The INCR+EXPIRE daily counter and the hash update live in one script evaluation, so concurrent workers cannot double-spend a token.

Layer 2 — resend cooldown with exponential step-up

Per-destination limits stop fan-out. Resend abuse on one number still burns budget and annoys a real user. Track a verification session (server-side id bound to the MSISDN after the first accepted send) and step the cooldown: 30s, then 60s, then 300s.

import math
from flask import Flask, request, jsonify

app = Flask(__name__)

COOLDOWNS = [30, 60, 300]  # seconds

def next_cooldown(attempt_index: int) -> int:
    return COOLDOWNS[min(attempt_index, len(COOLDOWNS) - 1)]

@app.post("/v1/auth/otp/send")
def send_otp():
    body = request.get_json(force=True)
    msisdn = body["msisdn"]
    session_id = body.get("session_id")  # issued after first send

    ok, wait_ms = allow_send(msisdn)
    if not ok:
        resp = jsonify({"error": "rate_limited", "scope": "destination"})
        resp.status_code = 429
        resp.headers["Retry-After"] = str(max(1, math.ceil(wait_ms / 1000)))
        return resp

    if session_id:
        attempt = int(r.get(f"otp:sess:attempts:{session_id}") or "0")
        last = r.get(f"otp:sess:last:{session_id}")
        if last is not None:
            elapsed = time.time() - float(last)
            need = next_cooldown(attempt - 1 if attempt > 0 else 0)
            if elapsed < need:
                retry = int(math.ceil(need - elapsed))
                resp = jsonify({"error": "rate_limited", "scope": "resend"})
                resp.status_code = 429
                resp.headers["Retry-After"] = str(retry)
                return resp
        pipe = r.pipeline()
        pipe.incr(f"otp:sess:attempts:{session_id}")
        pipe.set(f"otp:sess:last:{session_id}", str(time.time()), ex=3600)
        pipe.execute()

    # ... generate code, store hash, dispatch SMS, mint session_id on first send ...
    return jsonify({"session_id": session_id or "new-session-id"}), 200

The disabled "Resend" button is UX. The server enforces the timer and speaks 429 with Retry-After so honest clients back off without spinning.

Layer 3 — cost-centre guards

Pumping clusters in a handful of country prefixes. Per-MSISDN buckets alone will still let a bot walk a prefix at one-message-per-number pace. Add three controls above the destination bucket.

Prefix velocity. Maintain a sliding window counter per E.164 prefix (first 4–6 digits after +). Alarm and auto-throttle when sends/minute for that prefix exceed a baseline multiple of your real user traffic.

Global circuit breaker for unauthenticated send. Fail CLOSED: when tripped, unauthenticated /otp/send returns 503 immediately and never reaches the provider. Authenticated recovery flows can stay open on a separate path if you need them.

Prefix allow/deny policy. If you have zero users in a country, deny that prefix at the edge. Keep the list in config, not hardcoded in the handler.

from enum import Enum

class BreakerState(Enum):
    CLOSED = "closed"       # normal
    OPEN = "open"           # blocking unauthenticated sends
    HALF_OPEN = "half_open" # probe

class SendCircuitBreaker:
    def __init__(self, redis_client, threshold_per_min=120, open_for_sec=300):
        self.r = redis_client
        self.threshold = threshold_per_min
        self.open_for = open_for_sec

    def _state_key(self):
        return "otp:breaker:state"

    def record_send(self) -> None:
        key = f"otp:global:{int(time.time() // 60)}"
        count = self.r.incr(key)
        if count == 1:
            self.r.expire(key, 120)
        if count >= self.threshold:
            self.trip()

    def trip(self) -> None:
        self.r.set(self._state_key(), BreakerState.OPEN.value, ex=self.open_for)

    def allow_unauthenticated(self) -> bool:
        state = self.r.get(self._state_key()) or BreakerState.CLOSED.value
        if state == BreakerState.OPEN.value:
            ttl = self.r.ttl(self._state_key())
            if ttl is not None and ttl <= 0:
                self.r.set(self._state_key(), BreakerState.HALF_OPEN.value, ex=30)
                return True  # single probe window
            return False
        return True

    def probe_success(self) -> None:
        self.r.set(self._state_key(), BreakerState.CLOSED.value)

    def probe_failure(self) -> None:
        self.trip()

DENIED_PREFIXES = ("+2519", "+23480", "+22507")  # example: regions you do not serve

def prefix_allowed(msisdn: str) -> bool:
    return not any(msisdn.startswith(p) for p in DENIED_PREFIXES)

Wire prefix_allowed and allow_unauthenticated before allow_send. Whatever guards you build application-side, mirror the ceiling at the provider: the HTTP SMS API I use lets me cap outbound volume per key, which turned a 3 a.m. pumping attempt into a bounded few-dollar incident instead of an invoice conversation.

Layer 4 — make requests expensive before they reach SMS

Do not put a CAPTCHA on every send. Spend friction only when velocity rules say you are under attack: prefix counter above baseline, breaker half-open, or global 429 rate climbing.

When those signals fire, require an invisible challenge or a small proof-of-work on the request-code form only. Bind the solved challenge to a server session id, and bind that session to at most N distinct MSISDNs (N=1 is fine for login OTP). A bot that solved one challenge then cannot fan the same cookie across ten thousand numbers without solving again.

def session_may_target(session_id: str, msisdn: str, max_numbers: int = 1) -> bool:
    key = f"otp:sess:numbers:{session_id}"
    already = r.sismember(key, msisdn)
    if already:
        return True
    size = r.scard(key)
    if size >= max_numbers:
        return False
    pipe = r.pipeline()
    pipe.sadd(key, msisdn)
    pipe.expire(key, 3600)
    pipe.execute()
    return True

Under calm traffic the path stays one round-trip. Under pumping, compute and session cardinality become the tax, not a permanent UX tax on every real user.

Don't leak account existence while you're at it

The same send endpoint is often an oracle: {"error":"no_account"} for unknown numbers and {"ok":true} for known ones. Enumerators and pumpers both love that. Respond with the same body, same status, and comparable timing whether the number is registered or not. Always run the throttle layers first; only then branch into "create pending registration" versus "login OTP" behind a constant response shape.

If you must avoid sending SMS to unknown numbers for product reasons, still return the identical payload and schedule a no-op delay that matches the provider's p50 latency so timing does not re-open the oracle.

Verify-side limits

A code that is never checked is a pure cost event. Give verify its own bucket.

5 attempts per code, then invalidate the code.
Constant-time comparison (hmac.compare_digest in Python, timingSafeEqual in Node's standard library).
Single-use: delete or rotate on first success.
TTL 5–10 minutes (RFC 6238-style windows are a reasonable default for SMS OTP).

import hmac
import hashlib
import secrets

def store_code(session_id: str, code: str, ttl_sec: int = 600) -> None:
    digest = hashlib.sha256(code.encode("utf-8")).hexdigest()
    r.setex(f"otp:code:{session_id}", ttl_sec, digest)
    r.setex(f"otp:code:tries:{session_id}", ttl_sec, 0)

def verify_code(session_id: str, candidate: str) -> bool:
    tries_key = f"otp:code:tries:{session_id}"
    tries = int(r.incr(tries_key))
    if tries == 1:
        r.expire(tries_key, 600)
    if tries > 5:
        r.delete(f"otp:code:{session_id}")
        return False
    expected = r.get(f"otp:code:{session_id}")
    if not expected:
        return False
    got = hashlib.sha256(candidate.encode("utf-8")).hexdigest()
    ok = hmac.compare_digest(got, expected)
    if ok:
        r.delete(f"otp:code:{session_id}", tries_key)
    return ok

Track send_count / verify_count per prefix over a rolling window. A prefix with hundreds of sends and near-zero verifies is your cleanest automated detection signal — page on that ratio before finance pages on the invoice.

Incident runbook

When the spend graph bends up, execute in order. Do not start with root-cause analysis.

Flip the global unauthenticated send breaker to OPEN. Confirm /otp/send returns 503 without provider calls.
Snapshot the last 60 minutes of send logs (MSISDN, prefix, IP, session id, timestamp) to cold storage before retention rotates them.
Identify the top prefixes by send volume; add them to DENIED_PREFIXES or the provider-side block list immediately.
Lower the global per-minute threshold to a known-safe floor so HALF_OPEN probes cannot reopen the hose.
Invalidate in-flight OTP sessions created during the spike window.
Verify provider-side key caps are still enforced; tighten if the application breaker lagged.
Only then inspect bot signatures (UA, IP ASN, sequential MSISDN ranges) and write the permanent prefix/velocity rules.
Reopen the breaker in HALF_OPEN with a single canary prefix you actually serve; watch send:verify ratio for 15 minutes before CLOSED.

Monitoring dashboard spec

Graph these five series on one screen with 1-minute resolution:

Series	Source	Alert sketch
Sends by prefix	log/counter `otp.send` labeled by prefix	3× 7-day baseline for any prefix
Send:verify ratio by prefix	`otp.send` / `otp.verify_success`	ratio > 20 for 10 minutes
429 rate	HTTP status on `/otp/send` and `/otp/verify`	sustained > 30% of traffic
Breaker state	gauge 0=CLOSED 1=HALF_OPEN 2=OPEN	any transition to OPEN pages on-call
Spend rate	provider callback or local cost accumulator	absolute $/min ceiling

Checklist to ship before the next spike:

[ ] Atomic per-MSISDN token bucket (Lua or equivalent), daily cap included
[ ] Server-side resend cooldown with 429 + Retry-After
[ ] Prefix velocity counters + deny list for regions you do not serve
[ ] Global fail-CLOSED breaker on unauthenticated send
[ ] Challenge/PoW only when velocity rules trip; session-to-MSISDN cardinality bind
[ ] Identical responses (body + timing) for known and unknown numbers
[ ] Verify bucket: 5 tries, constant-time compare, single-use, 5–10 min TTL
[ ] send:verify ratio alert per prefix
[ ] Provider-side volume cap mirroring app limits
[ ] Runbook steps 1–8 posted where on-call actually looks

Exactly-Once Is a Lie: Building Idempotent SMS Sending with Retries That Don't Double-Text Your Users

SMSRoute Dev — Thu, 30 Jul 2026 07:13:09 +0000

The double-send postmortem

Tuesday 14:02. Support escalates: a user received the same OTP four times in ninety seconds. Logs show one logical "send login code" call from the app. The SMS provider dashboard shows four delivered messages. Billing shows four charges.

Here is the sequence that produced it.

Client POST /v1/messages with the OTP payload.
Provider accepts the message, enqueues delivery, begins writing 201 {"id":"msg_9f3a…"}.
The TCP connection stalls. Client-side read deadline fires at 10s. The client library surfaces TimeoutError.
Retry middleware treats timeout as retryable, fires the same POST again.
Provider has no memory of the first attempt from the client's point of view. It accepts a second message. User's phone buzzes again.

The message was sent on attempt one. The client simply never learned the outcome. Naive retry-on-timeout is the bug — not the network, not the provider. Every path where you cannot distinguish "never reached the server" from "server finished, response lost" will double-send unless you give the server a stable identity for the logical operation.

That identity is an idempotency key. Everything below exists because of this failure mode.

Idempotency keys done properly

Generate one UUIDv4 per logical message — once, when the business intent is created — not per HTTP attempt. Send it on every try:

POST /v1/messages HTTP/1.1
Host: api.example-sms.invalid
Content-Type: application/json
Idempotency-Key: 6b8e4f2a-9c1d-4e3f-a7b2-1d5c8e9f0a3b

{"to":"+15551234567","body":"Your code is 482901"}

Server contract you need (and must verify in the provider docs):

If the key has not been seen: process normally, store the response body and status keyed by the idempotency key, return that response.
If the key has been seen inside the retention window (typically 24h): return the stored status and body byte-for-byte. Do not send another SMS.
Concurrent requests with the same key: one wins; the other blocks or receives the same replay once the first completes.

Client generation (do this at intent time, persist the key next to the outbox row — see later):

import uuid
from dataclasses import dataclass

@dataclass(frozen=True)
class SmsIntent:
    to: str
    body: str
    idempotency_key: str

def new_sms_intent(to: str, body: str) -> SmsIntent:
    return SmsIntent(
        to=to,
        body=body,
        idempotency_key=str(uuid.uuid4()),
    )

Key scoping gotcha. The server must bind the key to a hash of the request body (method + path + body). If it only keys on the string you send, a retry that accidentally changes body (template fix, different OTP digit, locale tweak) silently returns the original response while your logs claim you "sent" the new content. I first hit the body-hash scoping issue against an SMS HTTP API where my retry wrapper reused the key after a template change — the server correctly replayed the old response, which is exactly what the spec says should happen and exactly not what I expected.

Rule: one key ↔ one immutable payload. Change the payload → new key. Never mint a fresh key inside the retry loop.

Which failures to retry (and which never)

Retrying the wrong status is how you turn one bad number into five failed API calls and a support ticket that looks like an outage.

Condition	Retry?	Notes
Connect timeout / TCP reset before request bytes leave	Yes	Safe; server never saw the request
Read timeout after request body fully sent	Yes, only with idempotency key	This is the double-send case above
`408 Request Timeout`	Yes
`425 Too Early`	Yes
`429 Too Many Requests`	Yes	Honor `Retry-After` (next section)
`500 / 502 / 503 / 504`	Yes	Cap attempts; provider may be partial
`400 Bad Request`	Never	Fix the payload
`401 Unauthorized` / `403 Forbidden`	Never	Fix credentials / permissions
`404 Not Found`	Never	Wrong path or resource
Provider validation, e.g. Twilio-style `21211` invalid `To`	Never	Five retries = five log lines of noise; some providers still meter lookup

import httpx

RETRYABLE_STATUS = frozenset({408, 425, 429, 500, 502, 503, 504})
NON_RETRYABLE_STATUS = frozenset({400, 401, 403, 404, 422})

# Provider-specific permanent failures (example codes from public Twilio error docs)
PERMANENT_PROVIDER_CODES = frozenset({
    21211,  # Invalid 'To' Phone Number
    21214,  # 'To' phone number cannot be reached
    21614,  # 'To' number is not a valid mobile number
})

def should_retry(exc: BaseException | None, response: httpx.Response | None) -> bool:
    if response is None:
        # connect error, DNS failure, or read timeout with no response object
        return isinstance(exc, (
            httpx.ConnectError,
            httpx.ConnectTimeout,
            httpx.ReadTimeout,
            httpx.RemoteProtocolError,
        ))
    if response.status_code in NON_RETRYABLE_STATUS:
        return False
    try:
        code = response.json().get("code")
        if code in PERMANENT_PROVIDER_CODES:
            return False
    except Exception:
        pass
    return response.status_code in RETRYABLE_STATUS

Timeout classification matters: a connect timeout never delivered bytes, so retry without fear of duplication even before keys exist. A read timeout after httpx finished writing the body is only safe when the same Idempotency-Key rides along.

Backoff that survives a real outage

Fixed 200ms retries during a provider blip synchronize every worker onto the same recovery second. Use full jitter, cap the sleep, and let Retry-After win on 429.

import random
import time
from email.utils import parsedate_to_datetime
from datetime import datetime, timezone

def backoff_seconds(attempt: int, base: float = 0.5, cap: float = 60.0) -> float:
    # Full jitter: sleep ~ U(0, min(cap, base * 2^attempt))
    # AWS Architecture Blog ("Exponential Backoff And Jitter") measured
    # full jitter as lower-tail latency and less herd correlation than
    # equal jitter or decorrelated forms under client thundering.
    exp = min(cap, base * (2 ** attempt))
    return random.uniform(0, exp)

def retry_after_seconds(response: httpx.Response) -> float | None:
    raw = response.headers.get("Retry-After")
    if raw is None:
        return None
    try:
        return max(0.0, float(raw))
    except ValueError:
        try:
            dt = parsedate_to_datetime(raw)
            if dt.tzinfo is None:
                dt = dt.replace(tzinfo=timezone.utc)
            return max(0.0, (dt - datetime.now(timezone.utc)).total_seconds())
        except (TypeError, ValueError, IndexError):
            return None

def send_with_retries(
    client: httpx.Client,
    intent: SmsIntent,
    max_attempts: int = 8,
) -> httpx.Response:
    last_exc: BaseException | None = None
    for attempt in range(max_attempts):
        try:
            resp = client.post(
                "/v1/messages",
                json={"to": intent.to, "body": intent.body},
                headers={"Idempotency-Key": intent.idempotency_key},
                timeout=httpx.Timeout(connect=5.0, read=15.0, write=10.0, pool=5.0),
            )
            if not should_retry(None, resp):
                return resp
            delay = retry_after_seconds(resp)
            if delay is None:
                delay = backoff_seconds(attempt)
            time.sleep(delay)
        except (httpx.ConnectError, httpx.ConnectTimeout,
                httpx.ReadTimeout, httpx.RemoteProtocolError) as exc:
            last_exc = exc
            if not should_retry(exc, None) or attempt == max_attempts - 1:
                raise
            time.sleep(backoff_seconds(attempt))
    if last_exc:
        raise last_exc
    raise RuntimeError("send_with_retries exhausted without response")

Retry-After on 429 is authoritative over your schedule — the provider is telling you when its limiter opens. Full jitter (U(0, capped_exp)) desynchronizes waiters better than equal jitter (half_exp + U(0, half_exp)); the AWS architecture blog on exponential backoff and jitter is the measurement reference most teams lean on here.

The outbox pattern for SMS

Do not call the SMS HTTP API inside the request handler or inside the DB transaction that creates the user session. A crash between COMMIT and the HTTP response leaves you with no durable record of intent — or worse, a commit and a half-finished retry storm.

Write the send intent into an sms_outbox table in the same transaction as the business change. A worker drains the table. The outbox row ID (or a dedicated UUID column) is the idempotency key.

CREATE TABLE sms_outbox (
    id              UUID PRIMARY KEY,
    to_e164         TEXT NOT NULL,
    body            TEXT NOT NULL,
    status          TEXT NOT NULL DEFAULT 'pending'
                    CHECK (status IN ('pending','in_progress','sent','dead')),
    attempt_count   INT  NOT NULL DEFAULT 0,
    max_attempts    INT  NOT NULL DEFAULT 8,
    next_attempt_at TIMESTAMPTZ NOT NULL DEFAULT now(),
    last_error      TEXT,
    provider_ref    TEXT,
    created_at      TIMESTAMPTZ NOT NULL DEFAULT now(),
    updated_at      TIMESTAMPTZ NOT NULL DEFAULT now()
);

CREATE INDEX sms_outbox_drain_idx
    ON sms_outbox (next_attempt_at)
    WHERE status = 'pending';

Business handler (same transaction):

import uuid
import psycopg

def create_login_challenge(conn: psycopg.Connection, user_id: int, e164: str, code: str) -> None:
    body = f"Your code is {code}"
    outbox_id = uuid.uuid4()
    with conn.transaction():
        conn.execute(
            "INSERT INTO login_challenges (user_id, code) VALUES (%s, %s)",
            (user_id, code),
        )
        conn.execute(
            """
            INSERT INTO sms_outbox (id, to_e164, body)
            VALUES (%s, %s, %s)
            """,
            (outbox_id, e164, body),
        )

Worker loop (~30 lines, runnable-shaped):

import os
import time
import httpx
import psycopg
from psycopg.rows import dict_row

DSN = os.environ["DATABASE_URL"]
BASE_URL = os.environ["SMS_API_BASE"]

def claim_batch(conn: psycopg.Connection, limit: int = 32) -> list[dict]:
    with conn.transaction():
        rows = conn.execute(
            """
            UPDATE sms_outbox
            SET status = 'in_progress',
                updated_at = now()
            WHERE id IN (
                SELECT id FROM sms_outbox
                WHERE status = 'pending'
                  AND next_attempt_at <= now()
                ORDER BY next_attempt_at
                FOR UPDATE SKIP LOCKED
                LIMIT %s
            )
            RETURNING *
            """,
            (limit,),
        ).fetchall()
    return rows

def mark_sent(conn: psycopg.Connection, row_id, provider_ref: str) -> None:
    conn.execute(
        """
        UPDATE sms_outbox
        SET status = 'sent', provider_ref = %s, updated_at = now()
        WHERE id = %s
        """,
        (provider_ref, row_id),
    )

def mark_retry_or_dead(conn: psycopg.Connection, row: dict, err: str) -> None:
    attempt = row["attempt_count"] + 1
    if attempt >= row["max_attempts"]:
        conn.execute(
            """
            UPDATE sms_outbox
            SET status = 'dead', attempt_count = %s,
                last_error = %s, updated_at = now()
            WHERE id = %s
            """,
            (attempt, err[:1000], row["id"]),
        )
        return
    delay = backoff_seconds(attempt)
    conn.execute(
        """
        UPDATE sms_outbox
        SET status = 'pending',
            attempt_count = %s,
            last_error = %s,
            next_attempt_at = now() + (%s || ' seconds')::interval,
            updated_at = now()
        WHERE id = %s
        """,
        (attempt, err[:1000], str(delay), row["id"]),
    )

def worker_once(client: httpx.Client) -> int:
    with psycopg.connect(DSN, row_factory=dict_row) as conn:
        batch = claim_batch(conn)
        for row in batch:
            intent = SmsIntent(to=row["to_e164"], body=row["body"],
                               idempotency_key=str(row["id"]))
            try:
                resp = send_with_retries(client, intent)
                if resp.status_code >= 400 and not should_retry(None, resp):
                    mark_retry_or_dead(conn, row, resp.text)
                    conn.commit()
                    continue
                resp.raise_for_status()
                ref = resp.json().get("id", "")
                mark_sent(conn, row["id"], ref)
                conn.commit()
            except Exception as exc:
                mark_retry_or_dead(conn, row, repr(exc))
                conn.commit()
        return len(batch)

def main() -> None:
    with httpx.Client(base_url=BASE_URL) as client:
        while True:
            n = worker_once(client)
            if n == 0:
                time.sleep(0.5)

if __name__ == "__main__":
    main()

Crash between provider accept and mark_sent: row stays in_progress or returns to pending via a sweeper that reclaims stale in_progress rows older than 2× your max HTTP budget. The next attempt reuses id as Idempotency-Key, so the provider replays the original accept. Effect on the user's phone: once.

Poison messages and the DLQ

A permanent failure that keeps cycling (21211, malformed body that slipped validation, destination that started rejecting) burns worker capacity and drowns metrics.

attempt_count + max_attempts on every row (schema above).
next_attempt_at advances with the same jittered exponential schedule so one bad row does not hot-loop.
At attempt_count >= max_attempts, set status = 'dead'. That row is the dead-letter queue; no separate system required on day one.
Alert on SELECT count(*) FROM sms_outbox WHERE status = 'dead' AND updated_at > now() - interval '1 hour' crossing a threshold — not on each individual failure. Individual failures during a provider incident are expected; DLQ depth growing while the provider is healthy means a code or data bug.

Optional sweeper for stuck claims:

UPDATE sms_outbox
SET status = 'pending',
    next_attempt_at = now(),
    updated_at = now()
WHERE status = 'in_progress'
  AND updated_at < now() - interval '5 minutes';

Verifying it actually works

Patterns without a chaos test are articles. Reproduce the original postmortem under control.

Run the provider (or a stub that records deliveries) behind toxiproxy.
Configure a toxic: timeout with timeout=0 on the response path after the stub has accepted the body — response never reaches the client, message is "delivered" server-side.
Drive one logical send through the outbox worker.
Assert: stub's delivery log length == 1 for that idempotency key; outbox row ends as sent; worker attempt_count may be > 1.

# stub_provider.py — records by idempotency key
from fastapi import FastAPI, Header, Request
from fastapi.responses import JSONResponse
import uuid

app = FastAPI()
delivered: dict[str, dict] = {}

@app.post("/v1/messages")
async def send(request: Request, idempotency_key: str = Header(alias="Idempotency-Key")):
    body = await request.json()
    if idempotency_key in delivered:
        prev = delivered[idempotency_key]
        return JSONResponse(prev["body"], status_code=prev["status"])
    msg_id = f"msg_{uuid.uuid4().hex[:12]}"
    payload = {"id": msg_id, "to": body["to"], "status": "queued"}
    delivered[idempotency_key] = {"body": payload, "status": 201}
    return JSONResponse(payload, status_code=201)

# toxiproxy: after stub is up on 9090
toxiproxy-cli create sms --listen 127.0.0.1:8888 --upstream 127.0.0.1:9090
toxiproxy-cli toxic add sms -t timeout -a timeout=0 -d downstream
# point SMS_API_BASE at http://127.0.0.1:8888 and run worker_once twice
# then: curl http://127.0.0.1:9090/admin/delivered | jq 'length'  → 1 per key

If the count is 2, your key is not stable across retries or the stub is not replaying. Fix that before shipping the backoff knobs.

Checklist

[ ] Idempotency key minted once per logical SMS, stored before any HTTP attempt
[ ] Key sent on every retry; never regenerated inside the retry loop
[ ] Provider confirmed to dedupe on the key and bind it to body hash for the retention window
[ ] Retry only 408/425/429/5xx, connect failures, and read timeouts — never 400/401/403/404 or permanent provider codes like 21211
[ ] Read-timeout retries gated on idempotency key presence
[ ] Full jitter backoff with ~60s cap; Retry-After overrides the local schedule on 429
[ ] SMS intent written to sms_outbox in the same DB transaction as the business write; worker drains with FOR UPDATE SKIP LOCKED
[ ] max_attempts + DLQ (status = 'dead') with alerts on DLQ depth; chaos test with timeout-after-accept proves one delivery per key

Your SMS Says "Sent" but Never Arrived: A Field Guide to DLRs, SMPP Status Codes, and Carrier Filtering

SMSRoute Dev — Wed, 29 Jul 2026 18:39:11 +0000

Your dashboard says sent. Your logs say accepted. Support is forwarding screenshots of empty inboxes. You re-send the same payload three times, the provider accepts all three, and still nothing lands on the handset. This is the gap between "the SMSC took your message" and "the phone actually displayed it" — and almost every SMS debugging session that goes sideways starts by collapsing those two states into one.

"Sent" is not "delivered": the four-hop lifecycle

An outbound SMS crosses four hops. Each hop can only honestly report what it controls:

app  →  provider API  →  SMSC  →  carrier  →  handset
         [accepted]     [sent]   [DLR...]    [DELIVRD?]

queued — your side enqueued the request; nothing has left your process yet.
accepted / sent — the SMSC acknowledged submit_sm. The message is in the carrier network's hands. This is the last status many dashboards ever show.
delivered — a delivery report (DLR) came back saying the handset accepted it.
undelivered / expired / rejected — a DLR (or a terminal error) says it will not arrive.

The operational rule: treat accepted/sent as "handed off," not "done." Anything you build on top of handoff-as-success — confirmation emails, unlock codes, "we texted you" UI — will lie to users the first time a carrier filters the traffic.

State machine you actually want:

queued → sent → delivered
              → undelivered
              → expired
              → rejected

Only move forward. Never overwrite delivered with a late sent.

Reading raw DLR states

Providers that speak SMPP under the hood (most of them, even over HTTP) surface a stat field on the DLR webhook. These are the values that matter and what each one implies you should do:

`stat`	Where it died	What to do
`DELIVRD`	Nowhere — handset got it	Mark success. Stop.
`EXPIRED`	Handset unreachable for the validity period (off, airplane mode, no signal)	Transient device issue. One delayed retry later is fine; do not hammer.
`UNDELIV`	Carrier could not deliver	Often number/porting/route. Check destination, try alternate route if you have one.
`REJECTD`	Carrier-side policy rejected it	Do not retry identical content. Inspect sender ID, template, content.
`ACCEPTD`	Intermediate ack only	Not terminal. Wait for a final DLR.
`UNKNOWN`	Carrier will not say	Common on some routes. Design UI/ops for "we don't know." Don't invent a status.

EXPIRED is about reachability over time, not content. REJECTD is almost always policy — content, sender reputation, or destination rules. UNKNOWN is not a bug in your parser; some carriers simply never return a final disposition. Store the raw stat string. Normalizing everything to a three-color enum before it hits the database is how you lose the only signal that explains a route failure three weeks later.

SMPP command_status errors worth knowing even over HTTP

HTTP APIs frequently re-expose SMPP command_status values in an error_code / error_message field when submit_sm itself fails. These fire before any DLR exists — the SMSC refused the submit.

ESME_RTHROTTLED (0x58) — you exceeded the bind-level submit rate. Back off and retry with jitter. Fix: lower sustained send rate or request a higher window. Do not open more binds to "get around" it; you will make throttling worse.
ESME_RINVDSTADR (0x0B) — destination address invalid (format, length, or obviously not a mobile number). Drop. Fix the input. Retrying the same MSISDN will fail the same way.
ESME_RMSGQFUL (0x14) — SMSC message queue is full. Transient. Retry with exponential backoff. If it persists across minutes, the route is unhealthy — page ops, don't keep dumping traffic into it.
ESME_RSUBMITFAIL (0x45) — generic submit failure. Treat as retryable a small number of times, then dead-letter. Correlate with provider status; this one often rides along with upstream carrier outages.

Map on ingest:

0x58  → retry (slow down)
0x0B  → drop  (fix input)
0x14  → retry (transient)
0x45  → retry then dead-letter

Do not collapse all non-zero command_status values into one provider_error bucket. The retry policy is different for each.

HTTP-era equivalents

Twilio-style error codes show up across the industry as either direct codes or documented equivalents:

30007 — Carrier violated / filtered. The carrier rejected the message on content or sender-reputation grounds. This is not a connectivity problem. Retrying the identical body from the same sender ID is worse than useless: it reinforces the reputation hit that got you filtered. Change content, review sender registration, or stop.
30003 — Unreachable handset. Phone off, out of coverage, or otherwise not accepting traffic right now. Comparable to EXPIRED/UNDELIV territory. One later retry is reasonable.
30005 — Unknown destination. Number is not a valid reachable mobile subscriber (landline, decommissioned, wrong country code). Drop and cleanse the list.
429 — Throttled. Same class as ESME_RTHROTTLED. Honor Retry-After if present; otherwise exponential backoff with jitter.

The key operational distinction: connectivity failures (30003, EXPIRED) tolerate a patient retry. Filter failures (30007, REJECTD) demand a content/sender change. Automating retries on 30007 is how teams dig the hole deeper.

Building the DLR webhook receiver correctly

Providers retry DLR webhooks that do not return 2xx quickly. If you do heavy work inline — DB joins, downstream HTTP, template rendering — you will double-process. Pattern that holds up:

Verify signature (next section).
Enqueue the raw payload.
Return 200 in under two seconds.
Process async with idempotency on (message_id, stat).

DLRs arrive twice. DLRs arrive out of order. A DELIVRD before your local sent transition is real and common under load. Your state machine only moves forward:

import json
import hashlib
import hmac
import time
from flask import Flask, request, abort
from queue import Queue

app = Flask(__name__)
work = Queue()

# message_id -> terminal-ish status rank
RANK = {
    "queued": 0,
    "ACCEPTD": 1,
    "sent": 1,
    "DELIVRD": 5,
    "EXPIRED": 5,
    "UNDELIV": 5,
    "REJECTD": 5,
    "UNKNOWN": 4,
}

def advance(current: str | None, incoming: str) -> str:
    if current is None:
        return incoming
    return incoming if RANK.get(incoming, 0) >= RANK.get(current, 0) else current

# stand-in for durable store
STATE: dict[str, str] = {}
SEEN: set[tuple[str, str]] = set()

def process_dlr(payload: dict) -> None:
    mid = payload["message_id"]
    stat = payload["stat"]
    key = (mid, stat)
    if key in SEEN:
        return
    SEEN.add(key)
    STATE[mid] = advance(STATE.get(mid), stat)
    # fan out to metrics, user-visible status, etc.

@app.post("/webhooks/dlr")
def dlr_webhook():
    raw = request.get_data()  # raw bytes — keep for HMAC
    if not verify_signature(raw, request.headers):
        abort(401)
    payload = json.loads(raw)
    work.put(payload)         # async worker calls process_dlr
    return {"ok": True}, 200

The receiver pattern above is what I run against a provider I use for transactional sends, whose DLR callbacks include the raw stat value — keeping the original SMPP state in your database beats normalizing it away when you're debugging a route weeks later.

Worker side is a single consumer loop over work. Swap Queue for Redis/SQS in production; the contract stays the same: ack HTTP fast, dedupe on (message_id, stat), only advance.

Verifying the webhook is really from your provider

Unauthenticated DLR endpoints get garbage, and eventually get spoofed statuses that flip user state. Verify HMAC-SHA256 over the raw body bytes with a shared secret. Three hard requirements:

Use the raw request body, not json.dumps(parsed) — re-serialization changes key order and whitespace and breaks valid signatures. This is the classic bug.
Compare with hmac.compare_digest, not == (timing-safe).
Enforce a timestamp tolerance window against replay.

import hmac
import hashlib
import time
import os

SECRET = os.environ["DLR_WEBHOOK_SECRET"].encode()
MAX_SKEW_SEC = 300  # 5 minutes

def verify_signature(raw_body: bytes, headers) -> bool:
    ts = headers.get("X-Signature-Timestamp", "")
    sig = headers.get("X-Signature", "")
    if not ts or not sig:
        return False
    try:
        ts_int = int(ts)
    except ValueError:
        return False
    if abs(time.time() - ts_int) > MAX_SKEW_SEC:
        return False
    # Many providers: hex(hmac_sha256(secret, f"{ts}." + body))
    message = ts.encode() + b"." + raw_body
    expected = hmac.new(SECRET, message, hashlib.sha256).hexdigest()
    # strip a leading "sha256=" if the provider uses that form
    given = sig.removeprefix("sha256=")
    return hmac.compare_digest(expected, given)

Reject missing headers, reject skew, reject bad digests — all as 401, before enqueue. Log the failure reason internally; do not echo it to the caller.

What to do with the data: delivery-rate observability

Store each terminal DLR with country, route/sender, stat, and timestamp. Build two ratios, not raw counts:

delivered / (delivered + undelivered + expired + rejected) per country
same ratio per route/sender

A sudden UNDELIV spike isolated to one carrier or route is a route problem — shift traffic, open a ticket with the provider, leave content alone. A uniform drop across routes that coincides with a template or sender-ID change is a content/reputation problem — stop the send, fix the template, do not retry the filtered body.

Alert on the ratio crossing a floor (for example, delivered ratio < 0.92 over a 15-minute window, minimum volume threshold so low-traffic countries do not page you). Alerting on absolute undelivered count fires every time you send more volume.

UNKNOWN should be tracked as its own bucket. Spiking UNKNOWN is a visibility regression, not necessarily a delivery regression — treat it differently in dashboards or you will chase ghosts.

The triage flowchart

"sent" in dashboard, user got nothing
│
├─ Do you have a DLR at all?
│   ├─ NO  → check submit errors
│   │         ├─ 0x0B / 30005     → fix MSISDN, drop
│   │         ├─ 0x58 / 429       → slow down, retry
│   │         ├─ 0x14 / 0x45      → retry w/ backoff; if persistent, route down
│   │         └─ none, just "sent"→ DLR path broken (webhook 4xx/slow, sig fail)
│   │
│   └─ YES → read stat / error
│             ├─ DELIVRD          → not an SMS issue; check handset/UI
│             ├─ EXPIRED / 30003  → handset unreachable; one delayed retry
│             ├─ UNDELIV          → number/route; try alt route, validate porting
│             ├─ REJECTD / 30007  → carrier filter; change content/sender, NO retry
│             └─ UNKNOWN          → carrier won't say; check ratio by route, don't invent status
│
└─ Ratios: one-route UNDELIV spike → route
           uniform drop after template change → content/sender

Cheat-sheet

accepted/sent = SMSC took it. Not delivered.
Store raw stat: DELIVRD, EXPIRED, UNDELIV, REJECTD, ACCEPTD, UNKNOWN.
EXPIRED/30003 → patient retry. REJECTD/30007 → fix content/sender, never identical retry.
0x58 throttle, 0x0B bad dest (drop), 0x14 queue full (retry), 0x45 submit fail (retry then dead-letter).
Webhook: verify HMAC on raw bytes with compare_digest, enqueue, 200 in <2s.
Dedupe (message_id, stat); state machine only advances.
Alert on delivered ratio per country and per route, not absolute counts.
One-route spike → route. Uniform drop after template change → content.

Why Your 160-Character SMS Became 3 Messages: GSM-7, UCS-2, and the Segmentation Math Nobody Reads

SMSRoute Dev — Wed, 29 Jul 2026 18:37:25 +0000

The bug report that starts it all

Support pasted this payload from a production OTP template:

Your code is 123456 — don't share it

Length check in the admin UI: 38 characters. Expected cost: 1 segment. Provider invoice: 2 segments per send. Volume was high enough that the discrepancy showed up as a real line item within a week.

The straight-looking string is not GSM-7. It contains U+2014 EM DASH (—) and U+2019 RIGHT SINGLE QUOTATION MARK (' in don't). Neither code point exists in the GSM-7 basic or extension tables. One out-of-table character forces the entire message into UCS-2 (UTF-16BE on the wire). The single-segment cap drops from 160 septets to 70 code units. Thirty-eight UCS-2 characters still fit in one segment — until marketing prepends a brand prefix and a URL, the total crosses 70, and you pay for two.

Byte-level view of the first offending character:

—  U+2014  →  UTF-16BE  20 14     (2 bytes, not a GSM septet)
'  U+2019  →  UTF-16BE  20 19     (2 bytes, not a GSM septet)

If those two glyphs had been ASCII hyphen-minus U+002D and apostrophe U+0027, the message would have stayed GSM-7 at 38 septets, one segment. The rest of this article is the exact math that turns “looks fine in the editor” into “3× billing.”

GSM-7 in 5 minutes: septets, not bytes

GSM-7 packs characters into 7-bit units called septets. A 140-byte SMS user-data field holds:

140 bytes × 8 bits = 1120 bits
1120 / 7 = 160 septets

So the familiar “160 characters” number is 160 septets, not 160 bytes.

Most printable ASCII plus a handful of Latin-1 letters live in the basic table and cost 1 septet each: A–Z, a–z, 0–9, space, !, ?, *, #, ä, ö, ñ, ü, à, Æ, ß, and so on.

A second extension table is reached by the escape septet 0x1B. Each extended character therefore costs 2 septets:

€  [  ]  {  }  \  ~  ^  |  and form feed

Common trap: a price string "Total: 12€". The € alone burns two septets. A template that was sized to 160 basic characters silently overflows when someone localizes the currency symbol.

Bit packing is why you cannot reason about SMS length with Buffer.byteLength(str, 'utf8'). UTF-8 byte length and GSM-7 septet length diverge as soon as an escape or a non-GSM code point appears.

When the encoding flips to UCS-2

The rule is absolute: if any character in the message is outside both GSM-7 tables, the full payload is re-encoded as UCS-2. Every character then occupies 16 bits. Capacity becomes:

140 bytes / 2 = 70 characters per single-segment message

No partial mode exists. One emoji, one smart quote, one en-dash — the whole message pays the UCS-2 tax.

Culprits injected daily by CMSes, Google Docs, and macOS “smart punctuation”:

Glyph	Code point	Name
`'`	U+2018	LEFT SINGLE QUOTATION MARK
`'`	U+2019	RIGHT SINGLE QUOTATION MARK
`"`	U+201C	LEFT DOUBLE QUOTATION MARK
`"`	U+201D	RIGHT DOUBLE QUOTATION MARK
`–`	U+2013	EN DASH
`—`	U+2014	EM DASH
`…`	U+2026	HORIZONTAL ELLIPSIS
	U+00A0	NO-BREAK SPACE
any emoji	various	outside BMP or non-GSM

Detection regex you can drop into a pre-send lint:

// Matches common smart punctuation + anything outside GSM-7-ish ASCII range
// for a quick reject/flag. Full classification is in the counter below.
const SMART_PUNCT = /[\u2018\u2019\u201C\u201D\u2013\u2014\u2026\u00A0]/;

function hasNonGsmHint(text) {
  if (SMART_PUNCT.test(text)) return true;
  // Emoji and most non-Latin scripts fall outside basic Latin + Latin-1 supplement used by GSM
  for (const ch of text) {
    const cp = ch.codePointAt(0);
    if (cp > 0xff) return true;
  }
  return false;
}

hasNonGsmHint is a fast tripwire, not a segment counter. Segment math needs the full tables.

Concatenation and the UDH tax

When a message exceeds one segment, the SMPP/SS7 stack splits it and attaches a User Data Header (UDH) so the handset can reassemble parts. The standard concatenation UDH is 6 bytes (length, IEI, IEL, ref, total, seq). Those 6 bytes steal space from the user-data field:

GSM-7 multipart:  (140 - 6) × 8 / 7 = 153.xx → 153 septets per segment
UCS-2 multipart:  (140 - 6) / 2           → 67 code units per segment

Cliff table (this is where invoices jump):

Encoding	Chars / septets	Segments	Cost factor
GSM-7	1–160	1	1×
GSM-7	161–306	2	2×
GSM-7	307–459	3	3×
UCS-2	1–70	1	1×
UCS-2	71–134	2	2×
UCS-2	135–201	3	3×

161 GSM-7 characters → 2 segments. 71 UCS-2 characters → 2 segments. There is no soft landing.

Segment-count formula, including the extension-character double-count:

function septetCount(text, basic, extended) {
  let septets = 0;
  for (const ch of text) {
    if (basic.has(ch)) septets += 1;
    else if (extended.has(ch)) septets += 2;
    else return null; // forces UCS-2 path
  }
  return septets;
}

function segmentCountFromSeptets(septets) {
  if (septets <= 160) return 1;
  return Math.ceil(septets / 153);
}

function segmentCountFromUcs2(chars) {
  if (chars <= 70) return 1;
  return Math.ceil(chars / 67);
}

A correct segment counter you can paste

Full classifier. Paste into Node 18+ and run.

const GSM7_BASIC = new Set([
  '@','£','$','¥','è','é','ù','ì','ò','Ç','\n','Ø','ø','\r',
  'Å','å','Δ','_','Φ','Γ','Λ','Ω','Π','Ψ','Σ','Θ','Ξ',
  'Æ','æ','ß','É',' ','!','"','#','¤','%','&','\'','(',')',
  '*','+',',','-','.','/','0','1','2','3','4','5','6','7',
  '8','9',':',';','<','=','>','?','¡',
  'A','B','C','D','E','F','G','H','I','J','K','L','M','N',
  'O','P','Q','R','S','T','U','V','W','X','Y','Z',
  'Ä','Ö','Ñ','Ü','§','¿',
  'a','b','c','d','e','f','g','h','i','j','k','l','m','n',
  'o','p','q','r','s','t','u','v','w','x','y','z',
  'ä','ö','ñ','ü','à'
]);

// Each of these costs 2 septets (ESC 0x1B + code)
const GSM7_EXTENDED = new Set([
  '\f','^','{','}', '\\','[','~',']','|','€'
]);

/**
 * @param {string} text
 * @returns {{ encoding: 'GSM-7'|'UCS-2', segments: number,
 *             charsRemaining: number, septets: number|null, length: number }}
 */
function smsSegments(text) {
  let septets = 0;
  let gsm = true;

  for (const ch of text) {
    if (GSM7_BASIC.has(ch)) {
      septets += 1;
    } else if (GSM7_EXTENDED.has(ch)) {
      septets += 2;
    } else {
      gsm = false;
      break;
    }
  }

  const length = [...text].length; // code points, not UTF-16 code units

  if (gsm) {
    const segments = septets <= 160 ? 1 : Math.ceil(septets / 153);
    const capacity = segments === 1 ? 160 : segments * 153;
    return {
      encoding: 'GSM-7',
      segments,
      charsRemaining: capacity - septets,
      septets,
      length
    };
  }

  const segments = length <= 70 ? 1 : Math.ceil(length / 67);
  const capacity = segments === 1 ? 70 : segments * 67;
  return {
    encoding: 'UCS-2',
    segments,
    charsRemaining: capacity - length,
    septets: null,
    length
  };
}

// --- edge-case tests ---
function assert(cond, msg) {
  if (!cond) throw new Error(msg);
}

// exactly 160 basic chars → 1 segment
assert(smsSegments('a'.repeat(160)).segments === 1, '160 basic');
assert(smsSegments('a'.repeat(160)).encoding === 'GSM-7', '160 enc');

// 161 basic → 2 segments
assert(smsSegments('a'.repeat(161)).segments === 2, '161 basic');

// € costs 2 septets: 159 basic + € = 161 septets → 2 segments
const euroBoundary = 'a'.repeat(159) + '€';
assert(smsSegments(euroBoundary).septets === 161, '€ septet count');
assert(smsSegments(euroBoundary).segments === 2, '€ segments');

// € at position 152 of an otherwise 160-char attempt:
// 151 basic + €(2) + 8 basic = 161 septets → 2 segments
const euro152 = 'a'.repeat(151) + '€' + 'a'.repeat(8);
assert(smsSegments(euro152).septets === 161, '€@152 septets');
assert(smsSegments(euro152).segments === 2, '€@152 segments');

// one emoji → UCS-2, 1 segment if total code points ≤ 70
assert(smsSegments('hello 😀').encoding === 'UCS-2', 'emoji enc');
assert(smsSegments('hello 😀').segments === 1, 'emoji seg');

// 71 UCS-2 chars → 2 segments
assert(smsSegments('你'.repeat(71)).segments === 2, '71 ucs2');
assert(smsSegments('你'.repeat(70)).segments === 1, '70 ucs2');

// original bug payload
const bug = "Your code is 123456 — don't share it";
assert(smsSegments(bug).encoding === 'UCS-2', 'bug enc');

console.log('all tests passed');
console.log(smsSegments(bug));
console.log(smsSegments(euroBoundary));

Run it:

node sms_segments.js

If any assertion fires, the tables or the UDH constants are wrong — fix before shipping the helper to production.

Sanitizing without mangling

Transliterate only the punctuation that never carries linguistic meaning:

const PUNCT_MAP = {
  '\u2018': "'", '\u2019': "'",
  '\u201C': '"', '\u201D': '"',
  '\u2013': '-', '\u2014': '-',
  '\u2026': '...',
  '\u00A0': ' ' // nbsp → space
};

function sanitizePunct(text) {
  return text.replace(
    /[\u2018\u2019\u201C\u201D\u2013\u2014\u2026\u00A0]/g,
    (ch) => PUNCT_MAP[ch]
  );
}

Apply sanitizePunct before smsSegments. The OTP example becomes:

Your code is 123456 - don't share it

GSM-7, 38 septets, 1 segment.

Do not strip or force-Latin user language. Turkish İ / ı, Greek, Cyrillic, CJK — those characters are intentional. Folding them to ASCII to save a segment corrupts the message. Detect, measure, and either accept UCS-2 cost or ask the product owner for a shorter copy in that locale.

NFKC normalization looks tempting ("ﬁ".normalize('NFKC') === "fi") but is unsafe as a blanket pre-pass. It can change Turkish dotted/dotless I behaviour and will decompose characters your legal copy deck required to stay composed. If you normalize, do it only on the punctuation set you control, not on the full string.

What the API actually tells you

Never trust only your local counter for billing reconciliation. Providers recompute segments against their own table revision and will bill what their SMSC emits. Read the segment count from the send response body, log it next to your local estimate, and diff them.

On the HTTP SMS API I use the send response includes the computed segment count, so I export it as a Prometheus metric and page when a deploy suddenly doubles it.

Practical wiring:

// after a successful send
const { segments } = providerResponse; // field name varies
metrics.smsSegments.observe(segments);
metrics.smsSegmentsPerBody.labels(templateId).observe(segments);

// alert: p95(segments) by template jumps after deploy
// e.g. from 1.0 → 2.0 within 15 minutes of a content change

A p95 jump from 1.0 to 2.0 on a single template ID almost always means smart quotes or an emoji landed in the copy. Pair the alert with the pre-send hasNonGsmHint lint in CI so the deploy never ships.

Cheat sheet

Four numbers

	Single segment	Multipart (per segment)
GSM-7	160 septets	153 septets
UCS-2	70 chars	67 chars

Extension characters (2 septets each)

€ [ ] { } \ ~ ^ | and form feed (\f)

Detection

/[\u2018\u2019\u201C\u201D\u2013\u2014\u2026\u00A0]/

Rules of thumb

One non-GSM character → whole message UCS-2.
161 GSM-7 septets or 71 UCS-2 chars → instant 2× cost.
€ in a 159-character body → 161 septets → 2 segments.
Sanitize curly quotes and dashes; never transliterate real language text.
Log provider-reported segments; alert on p95 regression per template.

Delivered is not delivered: SMS DLR status callbacks done right

SMSRoute Dev — Wed, 29 Jul 2026 09:44:39 +0000

If your app treats status=delivered as “the user got the code,” you have a silent failure mode. An SMS delivery receipt (DLR), status callback, or delivery webhook only reports how far a handoff chain got—not whether a human saw the message.

What the SMS handoff chain actually reports

your API call ──▶ provider accepted ──▶ carrier accepted ──▶ handset ack ──▶ human reads it
     │                   │                     │                  │              │
 2xx accept         "queued"/"sent"        "delivered"       (sometimes)     (never observable)
 (e.g. 201/200)

Treat any 2xx accept (Twilio often returns 201 Created; many providers return 200 OK) as accepted-for-processing, not sent. The status you later see usually reflects the furthest hop that bothered to report back. Some carriers ack when the message enters their network, not when the handset confirms. Others send nothing and your provider synthesizes a value.

Provider-neutral map of raw statuses into three app states:

Provider-ish status	Your state	Meaning
`queued` / `accepted`	`pending`	Provider has the message; carrier unknown
`sent`	`pending`	Submitted downstream; not handset-confirmed
`delivered`	`confirmed`	Someone downstream said OK (may be aggregator, not handset)
`undelivered` / `failed` / `rejected` / `expired`	`failed`	Terminal failure when present
no callback	`pending` → settle later	Common on some international routes; unknown, not success

Rules of thumb:

sent / accepted / queued — your provider has it. Says nothing about the handset.
delivered — a downstream hop said OK. On some routes that hop is an aggregator.
undelivered / failed / rejected / expired — trustworthy when you get them; absence of failure is not success.
No callback — treat as unknown. Do not invent success.

SMS DLR statuses: three states, not two

Model delivery as pending | confirmed | failed. Make pending first-class with a deadline—not an optimistic “it’ll be fine.”

STATUS_MAP = {
    "delivered":   "confirmed",
    "undelivered": "failed",
    "failed":      "failed",
    "rejected":    "failed",
    "expired":     "failed",
    "sent":        "pending",
    "queued":      "pending",
    "accepted":    "pending",
}

# Higher wins when two events race. Terminal failed must not flip back.
STATUS_PRIORITY = {
    "pending": 1,
    "confirmed": 2,
    "failed": 3,
}

def map_status(raw: str) -> str:
    # Unknown provider strings stay pending — never auto-confirm.
    return STATUS_MAP.get(raw, "pending")

Mapping unknown strings to pending (never confirmed) is the whole trick. Providers add statuses; a permissive default turns new failure modes into fake successes.

Idempotent SMS status webhooks

Delivery webhooks are public endpoints that assert things about billing and auth. Assume at-least-once delivery: duplicates are normal. Not every provider sends a stable event_id—if they don’t, derive one.

import hashlib

def event_key(evt) -> str:
    if getattr(evt, "event_id", None):
        return f"eid:{evt.event_id}"
    # Fallback when the provider omits event_id: hash stable fields.
    basis = f"{evt.message_id}|{evt.status}|{evt.timestamp}|{getattr(evt, 'error_code', '')}"
    return "h:" + hashlib.sha256(basis.encode()).hexdigest()

def handle(request):
    if not verify_signature(request.headers.get("X-Signature"), request.body, SECRET):
        return 403

    try:
        evt = parse(request.body)
    except ValueError:
        return 400  # poison payload: do not 2xx or the provider will retry forever

    key = event_key(evt)
    if store.seen(key):
        return 200  # authentic duplicate — ack only

    if not should_apply(evt):
        store.mark_seen(key)
        return 200  # stale / lower-priority — ack, do not regress

    apply(evt)  # prefer queue + worker; keep the HTTP path fast
    store.mark_seen(key)
    return 200

Return 2xx only for authentic traffic you have fully absorbed (including duplicates and deliberate no-ops). 403 on bad signature. 400 on unparseable bodies so bad payloads do not retry forever. At-least-once means you will see the same logical event twice; without idempotency keys you double-apply side effects (notifications, analytics, state flips).

Out-of-order DLR callbacks without clock-skew bugs

A late delivered must not revive a message you already marked failed. Comparing timestamps alone is wrong: clock skew, equal timestamps, and provider sequence gaps all break it.

Prefer this order:

Provider monotonic sequence / sid / event cursor when the API gives you one.
Else (message_id, status priority) with queued/sent/accepted → pending < delivered → confirmed < undelivered/failed/rejected/expired → failed, and terminal failed sticks.
Only then timestamp with skew tolerance (e.g. ignore a “newer” event if it is within a few seconds and lower priority).

SKEW_SECS = 30

def should_apply(evt) -> bool:
    cur = store.get(evt.message_id)
    if cur is None:
        return True

    # 1. Provider sequence / sid beats wall clock
    if evt.sequence is not None and cur.last_sequence is not None:
        if evt.sequence < cur.last_sequence:
            return False
        if evt.sequence == cur.last_sequence:
            return False  # already applied

    new_state = map_status(evt.status)
    cur_pri = STATUS_PRIORITY[cur.state]
    new_pri = STATUS_PRIORITY[new_state]

    # 2. Terminal failed sticks; never confirm after fail
    if cur.state == "failed" and new_state != "failed":
        return False

    # Same or lower priority without a newer sequence → no-op
    if new_pri < cur_pri:
        return False

    # 3. Timestamp only as tie-break, with skew tolerance
    if evt.sequence is None and new_pri == cur_pri:
        if evt.timestamp <= cur.last_timestamp + SKEW_SECS:
            return False

    return True

def apply(evt):
    new_state = map_status(evt.status)
    store.update(
        evt.message_id,
        state=new_state,
        raw=evt.status,
        last_timestamp=evt.timestamp,
        last_sequence=evt.sequence,
    )

You will eventually see delivered after failed for the same message_id on messy routes. Priority + sticky failure keeps auth and UX honest.

OTP fallback when DLR stays pending

Do not wait forever for a failure callback that may never arrive. On send, start a timer. 30–60 seconds is a UX default for OTP, not a protocol constant—measure p95 DLR latency per route and country and tune from there.

# UX default for OTP; replace 45 with measured p95 DLR latency for the route.
schedule(check_in=timedelta(seconds=45), message_id=msg.id)

def on_timer(msg_id):
    msg = store.get(msg_id)
    if msg.state != "pending":
        return

    # Auth-critical: pending-past-deadline is not "maybe still ok".
    invalidate_or_rotate_challenge(msg.session_id, msg.otp_id)
    store.update(msg_id, state="failed", raw="timeout_pending")

    offer_alternative(
        msg.user_id,
        channels=["voice", "email", "authenticator"],
    )

If the DLR later says failed, or the timer fires while still pending, invalidate or rotate the OTP / session challenge before you offer voice, email, or “resend.” Offering another channel while the original SMS code remains valid is an auth bug: the code can still arrive late on a delayed route and be used alongside the fallback. Same rule on terminal failed from the webhook—burn the challenge, then re-issue on the new channel.

Pending-with-deadline gives you a hook for that fallback. A two-state “sent / delivered” model does not.

Reconcile pending DLRs; do not trust webhooks alone

Webhooks get lost—dropped during deploys, blackholed by firewall rules, swallowed as 500s. Once a day (or hourly for OTP-heavy apps), query your own store and the provider API for stragglers.

-- Everything still pending past the UX/SLA window
SELECT message_id, provider_id, sent_at, raw_status
FROM sms_messages
WHERE state = 'pending'
  AND sent_at < NOW() - INTERVAL '15 minutes';

Settle rule:

def reconcile_row(row, provider_truth):
    if provider_truth is None:
        # No record upstream after N days → unknown, not delivered
        if row.sent_at < days_ago(7):
            store.update(row.message_id, state="failed", raw="reconcile_unknown")
        return

    state = map_status(provider_truth.status)
    # Same priority rules as live webhooks; still no confirm-after-fail
    fake = type("E", (), {
        "message_id": row.message_id,
        "status": provider_truth.status,
        "timestamp": provider_truth.timestamp,
        "sequence": provider_truth.sequence,
        "event_id": f"reconcile:{row.message_id}:{provider_truth.status}",
    })()
    if should_apply(fake):
        apply(fake)

Mark stubborn unknowns as failed (or a distinct unknown if you surface that in ops) after a bounded window—e.g. 7 days—not as confirmed. Reconciliation is a real query plus the same state machine, not a vague “thirty-line cron.”

Why SMS fails in ways no status explains

A chunk of international non-delivery is regulatory or policy, not a transport error. Many countries require pre-registration of alphanumeric sender IDs. On some routes and aggregators, DLRs can still look positive while the terminating network drops unregistered alphas. Other networks ban alphanumeric senders and rewrite them to short codes or generic numbers—users then ignore the message because the sender looks wrong. That is separate from encoding failures (UCS-2 vs GSM-7 truncating or mojibaking the body), which often show up as a different class of reject or a “delivered” message the user cannot read.

If delivery is fine in nine countries and terrible in the tenth, check sender-ID registration and encoding requirements for that destination before you rewrite retry logic. Soft signal: a clean upstream receipt does not prove the handset displayed your brand or your bytes.

PS. If you want a provider that exposes these statuses cleanly for API use, smsroute.cc is a no-KYC crypto-payment SMS API with free credits—useful for wiring the pending/confirmed/failed model above without a long procurement cycle. The state machine, webhook rules, and OTP invalidation apply regardless of vendor.

Your OTP resend button is a race condition (and it's charging you twice)

SMSRoute Dev — Wed, 29 Jul 2026 09:37:09 +0000

OTP resend race conditions cause duplicate SMS charges. Stop them with one challenge, an SMS idempotency key, and server-side dedupe—not a disabled button.

Every SMS OTP pipeline I’ve audited burns money the same way on day one. It rarely shows in staging. It shows on the carrier bill and in support: two message segments charged, two codes delivered, the second invalidating the first, user locked out on the code that arrived first. Duplicate MT cost is pure margin loss; the support load is the multiplier.

Client-side “disable Resend for 30 seconds” is UX. Mobile runtimes and flaky networks retry POST /otp/send with no human tap. If the server treats every request as “mint a new code and bill a new MT,” you lose. Ship button disable and a server idempotency contract together, or juniors will ship the button and call it done.

The OTP resend race condition (two charges, one failure)

user taps Resend  ──▶  POST /otp/send  ──▶ code A ──▶ provider call (~900ms)
user/network retry ──▶  POST /otp/send  ──▶ code B ──▶ provider call
                         store B (overwrites A)

SMS A arrives first → user enters A → server has B → "Invalid code."
You paid for A and B. Only B is valid. Support ticket writes itself.

The unit of work is not “send.” The unit is the challenge: one secret, one TTL, one attempt budget. Resend re-delivers that challenge. It does not mint a sibling.

One challenge, many SMS deliveries

If start_challenge only returns an existing row and you never show where plaintext comes from, the “resend same code” checklist is theater. You need a full send path: create-or-reuse, decrypt-or-generate in memory, then provider call.

Store the secret encrypted (or peppered-HMAC) at rest. Plaintext exists only in send-path memory—never in logs, never in a support tool dump.

import os, hmac, hashlib, secrets
from dataclasses import dataclass
from datetime import datetime, timedelta, timezone

# secrets only. Never math.random / random.random / PRNGs for OTPs.
def generate_code() -> str:
    return f"{secrets.randbelow(1_000_000):06d}"

def encrypt_code(code: str) -> bytes: ...
def decrypt_code(blob: bytes) -> str: ...

@dataclass
class Challenge:
    id: str
    user_id: str
    code_encrypted: bytes
    expires_at: datetime
    attempts: int
    delivery_count: int
    consumed: bool

def get_or_create_challenge(user_id: str) -> tuple[Challenge, str]:
    """Return (challenge, plaintext). Plaintext stays in send memory only."""
    existing = store.get_active(user_id)  # not expired, not consumed
    if existing and existing.age < timedelta(minutes=2):
        return existing, decrypt_code(existing.code_encrypted)

    code = generate_code()
    ch = store.put(Challenge(
        id=new_id(),
        user_id=user_id,
        code_encrypted=encrypt_code(code),
        expires_at=datetime.now(timezone.utc) + timedelta(minutes=5),
        attempts=0,
        delivery_count=0,
        consumed=False,
    ))
    return ch, code

Reuse window (here two minutes) is product policy: long enough to absorb double-taps and HTTP retries, short enough that a stalled user eventually gets a fresh secret after expiry.

Full send path—rate limits, idempotency slot, provider call, persist message_id before ACK:

def send_otp(user_id: str, phone: str, ip: str) -> dict:
    if not (limiter.check(f"otp:phone:{phone}", 5, 3600) and
            limiter.check(f"otp:ip:{ip}", 20, 3600)):
        raise RateLimitError("otp send rate limited")

    challenge, code = get_or_create_challenge(user_id)

    # Intentional resend bumps delivery_count only after a finalized prior send.
    # Network retries of *this* slot reuse the same key (see table below).
    slot = challenge.delivery_count
    idem_key = f"{challenge.id}:{slot}"

    # Local dedupe even when the upstream API is weak or ambiguous.
    if not redis.set(f"sms:idem:{idem_key}", "pending", nx=True, ex=300):
        return {"status": "already_accepted", "challenge_id": challenge.id}

    try:
        result = sms.send(
            to=phone,
            text=f"Your code is {code}",
            idempotency_key=idem_key,  # Twilio-style when the API supports it
        )
    except ProviderTransientError:
        # 5xx / timeout: allow retry with the SAME key; do not mint a new slot.
        redis.delete(f"sms:idem:{idem_key}")
        raise
    except ProviderRateLimitError:
        # 429: do not spin a new idempotency key to "get through."
        raise

    # 2xx with provider message_id → persist BEFORE acking the client.
    store.save_delivery(challenge.id, slot, result.message_id)
    store.increment_delivery_count(challenge.id)
    redis.set(f"sms:idem:{idem_key}", result.message_id, ex=86400)
    return {
        "status": "sent",
        "challenge_id": challenge.id,
        "message_id": result.message_id,
    }

Your API should also accept an optional client Idempotency-Key on POST /otp/send. The Resend button generates a new key (new delivery slot). HTTP retries replay the same key. Button disable alone never replaces that contract.

Provider idempotency keys (and Redis NX)

“Any HTTP SMS API is fine” is false for billing safety. Twilio-style Idempotency-Key (or equivalent) collapses duplicate POSTs into one MT. Generic “send” endpoints without that semantic will double-charge on retry unless you wrap them.

Practical rule:

Prefer a provider that honors a Twilio-style Idempotency-Key (or documents equivalent dedupe).
Otherwise your Redis SET key NX EX … wrapper is the idempotency layer—put it in front of every billable send.
Keys must be stable for a retry of the same logical delivery (challenge_id + delivery_slot or the client idempotency key), and distinct for an intentional resend.

When to retry, when you are charged

Outcome	What to do	Charge / key rule
429 rate limit	Back off; surface retry-after.	Do not retry with a new idempotency key to bypass the limit.
5xx or timeout	Retry the send.	Reuse the same idempotency key; clear only your local NX “pending” marker if you need the retry to proceed.
4xx (bad number, invalid payload)	Fix input or stop.	Do not retry blindly; no new key will help a permanent client error.
2xx + provider `message_id`	Persist `message_id` (and slot) before ACKing the client.	That row is your proof against a second billable push for the same slot.

Charge timing differs by vendor (accept vs. deliver). You cannot control carrier handoff, but you can ensure two app retries do not become two accepted sends. Persist provider ids first; then ACK. If the process dies after provider success but before DB write, reconciliation jobs use the idempotency key / message id—not a blind resend with a fresh key.

Rate limit phone + IP against SMS pumping

Two axes, always:

Per phone — stops one number from draining balance (and stops user self-DoS).
Per IP — slows distributed abuse from one botnet node.

Per-IP alone fails when attackers cycle numbers. Per-phone alone fails when they spray from many IPs. Together you raise the cost of SMS pumping (fraud that drives traffic toward premium-rate or revenue-share numbers so the attacker skims carrier share while you pay MT).

allow = (
    limiter.check(f"otp:phone:{phone}", limit=5,  window=3600) and
    limiter.check(f"otp:ip:{ip}",       limit=20, window=3600)
)

Tune with real traffic. Add velocity alerts on sends per country and on sudden spikes in failed verifies after successful sends—that pattern is often pumping or bot signups, not UX confusion.

Verify: atomic attempts, constant-time, single-use

The naive “read → compare → save attempts” path loses races: two parallel verifies both read attempts == 4, both succeed the check, both authenticate. Increment must be conditional and atomic, and success must consume in a compare-and-swap style op.

def verify(user_id: str, submitted: str) -> bool:
    # Atomic claim of one attempt, or fail closed.
    # SQL sketch:
    #   UPDATE challenges
    #      SET attempts = attempts + 1
    #    WHERE user_id = :uid
    #      AND consumed = false
    #      AND expires_at > :now
    #      AND attempts < 5
    #    RETURNING *
    ch = store.claim_verify_attempt(user_id, max_attempts=5, now=datetime.now(timezone.utc))
    if ch is None:
        return False

    plaintext = decrypt_code(ch.code_encrypted)
    match = hmac.compare_digest(plaintext, submitted.strip())
    if not match:
        return False

    # Single-use: only one winner if two verifies race after a match.
    if not store.consume_if_active(ch.id):
        return False
    return True

Details that matter in production:

Attempt budget burns even on mismatch—and the burn happens in the atomic claim, not after a slow compare.
hmac.compare_digest (constant-time) for the secret compare—no early-return string equality.
Consume on success so a replayed code cannot authenticate twice.
Fail closed when the claim or consume loses a race; do not “helpfully” retry the compare in process.

Optional hardening: store a peppered HMAC and the ciphertext, verify against the HMAC so the verify path never needs decrypt. Resend still decrypts once in send memory only.

When the code never arrives (sender ID + encoding)

Idempotency does not help if the MT is filtered. In many countries alphanumeric sender IDs (MyBrand) must be pre-registered, and in some they are blocked outright. Your pipeline returns 200, the provider accepted the message, and the handset gets nothing—you learn from churn, not from staging.

We publish an open country dataset (CC-BY-4.0) with columns including sender_id_regime, registration_required, charset_class, regulatory basis, and last-verified date:

github.com/SMSRoute-cc/sms-sender-id-regulations

Same table, second foot-gun: charset_class. GSM-7 holds 160 characters single-segment and 153 per segment when concatenated. UCS-2 (common once you leave basic Latin) holds 70 single-segment and 67 concatenated. A template sized for one GSM-7 segment becomes two or three UCS-2 segments without a single logic bug in your OTP state machine—and you pay per segment.

Check registration regime and charset before you freeze copy and sender ID, not after a country-specific outage.

Production checklist

[ ] One active challenge per user; resend re-delivers, does not regenerate inside the reuse window
[ ] Full send path: get-or-create → plaintext only in memory → provider call
[ ] Code encrypted or peppered-HMAC at rest; plaintext never logged
[ ] OTP from secrets / CSPRNG only—reject math.random and insecure RNGs
[ ] Idempotency key per delivery slot (Twilio-style Idempotency-Key or your Redis NX wrapper)
[ ] Client Resend button disabled and server idempotency contract enforced
[ ] Retry map: 429 no new key; 5xx/timeout same key; 2xx persist message_id before client ACK
[ ] Rate limit per phone and per IP; watch for SMS pumping velocity
[ ] Verify: atomic attempt claim, constant-time compare, single-use consume
[ ] Sender-ID rules checked per country you ship to (sender_id_regime, registration_required)
[ ] Templates budgeted for GSM-7 160/153 vs UCS-2 70/67 (charset_class)

Wire this once at the challenge layer and duplicate SMS charge classes drop out of the bill. For a concrete HTTP SMS API with crypto payment and free test credits, smsroute.cc is what we use behind the same idempotency wrapper—pair it with the sender-ID dataset above before you open a new country.

Sending transactional SMS over plain HTTP: pricing, error codes, and DLR callbacks

SMSRoute Dev — Wed, 29 Jul 2026 09:35:10 +0000

Sending transactional SMS over plain HTTP: pricing, error codes, and DLR callbacks

Twilio trials die to compliance holds, card declines, or 10DLC review—not bad SDKs. This guide covers crypto-prepaid HTTP SMS APIs as backup OTP paths: multi-home design, DLR handling, real errors, and what no-KYC actually changes.

TL;DR

Twilio (and peers) win on compliance tooling and ecosystem; they hurt when a single account freeze blocks login SMS.
“No-KYC” means light signup and prepaid balance. Your traffic still hits carrier filters. It is not a legal shield.
Do not assume Stripe-style idempotency keys exist on thin SMS gateways. Prefer vendor-documented keys; otherwise enforce at-most-once in your DB before POST.
Abstract senders behind an interface, keep a full-stack CPaaS for regulated traffic, and use a prepaid HTTP route for overflow and staging.
Prices move weekly. Model delivered cost by destination, not marketing “from” rates.
You remain sender of record under TCPA, GDPR/ePrivacy, DLT, and local rules—crypto prepay does not transfer that duty.

Why teams add a second SMS path

Price rarely starts the ticket. These do:

Account review loops. A2P 10DLC and international sender rules exist for good reasons. A traffic-shape change, undelivered burst, or content complaint can park the account in manual review. If that account is your only OTP channel, authentication stops.

KYC and business verification delay. Sole props, foreign entities, and early products without a long paper trail wait on document rounds. Legitimate teams still lose days. Hackathons, staging, and pre-incorporation builds cannot absorb that.

Card and procurement friction. Minimum top-ups, soft-declined cross-border cards, and vendor-master requirements block sends that engineering already finished. Crypto-settled prepaid balance removes the card network from the critical path for teams already paying infra in stablecoins.

API surface vs. time-to-first-SMS. Messages, Messaging Services, Lookup, Verify—you pay for maturity with concepts you may not need on day one. Some products only need authenticated POST with to, text, optional sender, and a DLR callback.

Opacity when delivery drops. You need DLR codes and enough detail to tell content failure from operator failure from upstream route failure. Leaving Twilio does not fix opacity by itself; pick vendors that expose status callbacks you can store and chart.

Runbook, not manifesto: multi-home OTP. Keep a compliant full-stack provider for US 10DLC and branded traffic. Keep a prepaid HTTP route for transactional overflow and environments that must not share production CPaaS credentials.

What “no-KYC” means (and what it does not)

In SMS, identity checks are how networks fight grey routes, phishing OTPs, and SIM-farm spam. Skipping formal KYC usually means one of:

Email + prepaid only — top up, send, freeze on abuse signals; no passport on day one.
KYC delayed until threshold — under N messages or N spend, no docs; cross the line and forms appear.
KYC on features — long codes, number rental, or voice need docs; raw outbound SMS might not.

Price these risks in:

Sudden cutoff — little contract leverage; upstream flags can freeze balance mid-incident.
Sender ID lottery — India DLT, EU sender policies, US A2P: alphanumeric “just send it” fails or gets rewritten. Light onboarding often cannot register brands for you.
Delivery variance — discount routes accept then die as carrier-filtered / undelivered with thin detail.
Settlement risk on crypto — when credits post (after N confirmations), which assets (USDT TRC20 vs ERC20 fee profiles differ), refund policy (often none).

Compliance callout (must-fix)

No-KYC is an onboarding posture, not a compliance certificate. You remain the sender of record. Crypto prepay and thin signup do not alter duties under TCPA, GDPR/ePrivacy, India DLT, or other local telecom and consent rules. Do not put primary production auth recovery solely on an anonymous or lightly identified route. Use these paths for backup, staging, low-risk transactional overflow, and corridors where you already meet consent and registration requirements by your own process.

Rational uses: internal alerts, non-US transactional tests, backup OTP on low-risk apps, early validation.

Irrational uses: primary US marketing SMS, guaranteed 10DLC brand registration, regulated healthcare/finance notify at scale, traffic you cannot afford to lose for 48 hours.

Provider comparison without fake peers

Do not treat “privacy-first HTTP SMS” as one vendor beside Twilio. Compare named products on public docs, then a separate row class for thin prepaid gateways.

Criterion	Twilio	Plivo	Vonage API	Thin prepaid HTTP gateways (category)
KYC / business verification	Required for production-scale and 10DLC; trial limited	Required for full features; trial common	Required for production; profile checks common	Often email + prepaid; KYC by volume or feature
Native crypto top-up	No	No	No	Sometimes (USDT/USDC/BTC prepaid)
Trial / free credit	Trial credit pattern (verify current offer)	Trial credits common	Trial credits common	Small test credit or pay-first—verify
Outbound SMS price	Verify on vendor price API; date-stamp your quote	Verify on vendor price API; date-stamp	Verify on vendor price API; date-stamp	Verify on vendor rate card; cheap routes trade quality
Time to first SMS	Console + verified numbers; plan for longer with compliance	Moderate	Moderate	Often minutes after API key + prepaid
Strength	Ecosystem, Verify, compliance tooling	Competitive SMS API	Global voice/SMS heritage	Speed, crypto rail, minimal ceremony
Weakness	Review friction, complexity	Traditional onboarding	Enterprise sales gravity	Abuse freezes, uneven routes, weaker brand registration

Engineer reading: need Verify-style orchestration, number inventory, DPAs, and registered programs → Twilio/Plivo/Vonage. Need spare capacity, crypto treasury settlement, or a narrow transactional pipe → a thin HTTP gateway is a narrower tool, not a moral upgrade.

Prices: they change weekly. Scrape or call each vendor’s rate card or pricing API; store destination, price, and retrieval date. Delete any mental “US base ~$0.0079” anchor unless you cite a dated public page you actually pulled.

Example vendor (footnote-level)

For a concrete prepaid HTTP option with crypto top-up and light onboarding, smsroute.cc is one example to evaluate beside others: test DLR webhooks, credit-post rules, and corridor quality yourself before it earns traffic weight. The durable engineering value is the interface and fallback pattern below—not any single hostname.

Durable design: `SmsSender` + fallback

Lead with code you own.

from typing import Protocol

class SmsSender(Protocol):
    def send(self, *, to_e164: str, body: str, client_ref: str) -> str:
        """Queue one SMS. Returns provider message id. Raises on hard failure."""
        ...

class MultiHomeSmsSender:
    """Try primary (e.g. Twilio); on provider outage / 5xx, fail over once."""

    def __init__(self, primary: SmsSender, secondary: SmsSender):
        self.primary = primary
        self.secondary = secondary

    def send(self, *, to_e164: str, body: str, client_ref: str) -> str:
        try:
            return self.primary.send(
                to_e164=to_e164, body=body, client_ref=client_ref
            )
        except TransientProviderError:
            return self.secondary.send(
                to_e164=to_e164, body=body, client_ref=client_ref
            )

Idempotency (correct default for grey/thin APIs):

Send an idempotency key if the vendor documents it (header or body field). Copy names from their OpenAPI.
If they do not, enforce at-most-once in your database—e.g. unique (user_id, purpose, time_window)—before POST. Do not assume Stripe-style Idempotency-Key behavior exists on HTTP SMS APIs that never documented it.
Retries without your own dedupe double-text and double-charge on prepaid balance.

Keep regulated US A2P and marketing on the full-stack account. Point overflow, staging, and break-glass weights at the prepaid client in your router. Store both providers’ message IDs next to user_id / session id.

When plain HTTP SMS is enough

Enough when the contract is: auth POST in, DLR callback out, prepaid balance, no Messaging Service topology. Password resets, app alerts, CI pages to on-call, prototype OTP.

Not enough alone when carriers require registered traffic programs, when opt-in evidence must sit beside the send path, or when finance needs MSAs/DPAs before go-live.

Send path: illustrative HTTP shape

ILLUSTRATIVE ONLY—field names, paths, and auth differ. Copy from your vendor OpenAPI. Do not ship this host.

curl (accept + realistic failure)

export SMS_API_KEY='YOUR_KEY'
export SMS_BASE='https://api.vendor.example/v1'   # replace from docs

# Success-shaped accept (queued ≠ delivered)
curl -sS -X POST "$SMS_BASE/messages" \
  -H "Authorization: Bearer $SMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155550123",
    "from": "MYAPP",
    "text": "Your code is 482193. Expires in 10 minutes.",
    "callback_url": "https://example.com/webhooks/sms-dlr",
    "client_ref": "otp:user:42:1710000000"
  }'
# Example 200 body:
# {"id":"msg_01HZX…","status":"queued","to":"+14155550123"}

# Non-200 you must handle (example shapes—map to vendor JSON)
curl -sS -o body.json -w "%{http_code}\n" -X POST "$SMS_BASE/messages" \
  -H "Authorization: Bearer $SMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":"4155550123","text":"missing plus and country"}'
# HTTP/1.1 422
# {"error":{"code":"invalid_to","message":"E.164 required","request_id":"req_…"}}

Only add an idempotency header when docs say so:

# -H "Idempotency-Key: otp-user-42-1710000000"

DLR callback (store this; drive UX from it)

{
  "id": "msg_01HZX…",
  "client_ref": "otp:user:42:1710000000",
  "to": "+14155550123",
  "status": "delivered",
  "error_code": null,
  "error_message": null,
  "occurred_at": "2025-11-12T14:02:11Z"
}

Failure-shaped DLR example:

{
  "id": "msg_01HZY…",
  "client_ref": "otp:user:42:1710000000",
  "to": "+14155550123",
  "status": "failed",
  "error_code": "carrier_filtered",
  "error_message": "Downstream filtered",
  "occurred_at": "2025-11-12T14:02:44Z"
}

Python (stdlib): treat accept as queued

import json
import os
import urllib.error
import urllib.request

API_KEY = os.environ["SMS_API_KEY"]
BASE = os.environ["SMS_BASE"]  # from vendor docs

payload = {
    "to": "+14155550123",
    "from": "MYAPP",
    "text": "Your code is 482193. Expires in 10 minutes.",
    "callback_url": "https://example.com/webhooks/sms-dlr",
    "client_ref": "otp:user:42:1710000000",
}

req = urllib.request.Request(
    f"{BASE}/messages",
    data=json.dumps(payload).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    method="POST",
)

try:
    with urllib.request.urlopen(req, timeout=30) as resp:
        body = json.loads(resp.read().decode())
        # persist body["id"] with client_ref; wait for DLR for UX
        print(resp.status, body)
except urllib.error.HTTPError as e:
    err = e.read().decode()
    # log status + err JSON; map invalid_to / rate_limit / payment_required
    raise SystemExit(f"{e.code} {err}")

Production rules that matter:

Secrets manager; send-only key if the vendor supports scoped keys.
E.164 normalize before POST (libphonenumber); reject garbage in UI.
Accept 2xx = queued, not delivered. UX and “resend OTP” timers follow DLR.
Rate-limit OTP in your app (user, IP, device). The gateway is not your anti-abuse layer.
Chart acceptance rate, DLR success within 60s, error histogram by country, cost per delivered message.

Errors worth wiring (Twilio lingua franca + thin JSON)

Thin APIs return their own JSON; on-call still searches Twilio-shaped codes. Map both in one dashboard.

Invalid destination (Twilio 21211 / vendor `invalid_to`)

Not E.164: missing country code, 00 prefix, extension junk, email field on the SMS path. Validate with libphonenumber; tell the user to check country code.

Rate limit (HTTP 429 / Twilio 20429)

Account or key QPS/daily cap. OTP retry storms, shared stage/prod keys, bulk on a transactional credential. Fix with app-level governors, jittered backoff, separate keys, short “already sent” cache per user. Ask for a limit bump only after your governors exist.

Carrier filtered (Twilio 30007 / vendor `carrier_filtered`)

Spam filters, bad templates, unregistered corridors, shorteners on first contact, spike to one MNO. Plain OTP copy, no mystery shorteners, register sender IDs where required, split marketing from transactional, switch route or vendor for that ISO—not necessarily all traffic.

Also monitor

Signal	Action
30003 unreachable handset	Capped later retry
30005 unknown handset	Stop retry; mark bad number
30008 unknown	Sample and watch upstream
21610 unsubscribed (Twilio-shaped)	Honor opt-out in your DB globally
402 / payment_required	Credits not posted or wrong product wallet

What good evaluation looks like

Replace posture prose with a soak test you record:

Field	Example log (fill with your run)
Date	2025-11-12
N messages	50
Destinations	US, DE, BR (example)
Template	short OTP, no URL
Delivered (DLR)	record count / N
Dominant failures	e.g. invalid_to, carrier_filtered
Sample DLR	store one delivered + one failed JSON
Credit post	tx hash → balance visible after T minutes
Refund policy	none / partial / N/A—copy from docs

If a vendor will not give DLR detail or status history, they are not an auth-path candidate.

FAQ

How to choose a crypto-prepaid SMS API

Checklist, not logos:

DLR webhooks with stable statuses and error codes you can store
Idempotency documented or clear acceptance that you dedupe in your DB
Credit-post rules (asset, network, confirmations, which balance bucket)
Refund policy (expect none on crypto prepaid)
Public status page and reachable incident channel
E.164 and sender-ID docs per corridor
50-message soak to countries you care about before any traffic weight

Is no-KYC SMS legal for OTPs?

Light onboarding is not inherently illegal. Sending without required consent, without required sender registration, or for fraud is. TCPA, GDPR/ePrivacy, DLT, and local rules still apply to you. See the compliance callout above.

How much does SMS cost?

There is no stable universal cent figure. US, EU, and long-haul routes differ; verify products that wrap fraud checks cost more per successful verification than raw SMS. Model delivered cost from your vendor’s rate card on the day you price the feature.

Can I keep Twilio numbers and only switch send path?

Not as a silent swap. Numbers are provider inventory unless you port. Abstract SmsSender implementations; porting is a separate project with timeline risk.

Crypto paid—why do sends still fail?

Balance is not route access. You still get invalid numbers, 429/20429, carrier filtered, unregistered sender IDs, and credits posted to the wrong product. Confirm wallet, sender allowance, and egress IP allowlists for CI and production.

Conclusion

Twilio remains the default when you need compliance depth and a wide surface. It is also a single point of failure when review queues, KYC rounds, or card rails seize up. A crypto-prepaid, light-KYC HTTP SMS path is a sharp backup for staging, overflow OTP, and lean transactional sends—if you measure delivery, enforce at-most-once in your own datastore when vendors lack idempotency, honor consent, and refuse to run primary auth recovery on anonymous rails alone. Match stack to corridor and risk; put DLR metrics and multi-home routing in your code so no single vendor’s manual review decides whether users can log in.