DEV Community: SMSRoute Dev

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.

Twilio Alternatives That Accept Crypto and Skip KYC

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

Twilio Alternatives That Accept Crypto and Skip KYC

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.

DEV Community: SMSRoute Dev

Delivered is not delivered: SMS DLR status callbacks done right

What the SMS handoff chain actually reports

SMS DLR statuses: three states, not two

Idempotent SMS status webhooks

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

OTP fallback when DLR stays pending

Reconcile pending DLRs; do not trust webhooks alone

Why SMS fails in ways no status explains

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

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

One challenge, many SMS deliveries

Provider idempotency keys (and Redis NX)

When to retry, when you are charged

Rate limit phone + IP against SMS pumping

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

When the code never arrives (sender ID + encoding)

Production checklist

Twilio Alternatives That Accept Crypto and Skip KYC

Twilio Alternatives That Accept Crypto and Skip KYC

TL;DR

Why teams add a second SMS path

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

Provider comparison without fake peers

Example vendor (footnote-level)

Durable design: SmsSender + fallback

When plain HTTP SMS is enough

Send path: illustrative HTTP shape

curl (accept + realistic failure)

DLR callback (store this; drive UX from it)

Python (stdlib): treat accept as queued

Errors worth wiring (Twilio lingua franca + thin JSON)

Invalid destination (Twilio 21211 / vendor invalid_to)

Rate limit (HTTP 429 / Twilio 20429)

Carrier filtered (Twilio 30007 / vendor carrier_filtered)

Also monitor

What good evaluation looks like

FAQ

How to choose a crypto-prepaid SMS API

Is no-KYC SMS legal for OTPs?

How much does SMS cost?

Can I keep Twilio numbers and only switch send path?

Crypto paid—why do sends still fail?

Conclusion

Durable design: `SmsSender` + fallback

Invalid destination (Twilio 21211 / vendor `invalid_to`)

Carrier filtered (Twilio 30007 / vendor `carrier_filtered`)