Short answer: treat an order alert as an auditable event with a bounded SMS attempt, not as a message to resend until a carrier says something reassuring. Store the rendered body, sender-registration context, country, consent, provider handoff, and every terminal reason. That record lets a marketplace explain a missed seller alert and keeps a telehealth-style login challenge from becoming a replayable pile of codes.
The decision record starts with invariants
The first invariant is identity. Create one immutable notification ID for “order 81472 is ready,” then attach an attempt ID to each transport submission. A phone number is not an event key; a seller can receive two legitimate orders, and one order can have several transport attempts.
The second invariant is evidence. Persist the exact rendered text, a body signature, sender ID, destination country, consent reference, template version, and timestamps in UTC. A template ID alone cannot prove what crossed the provider boundary. Registration approval is also scoped: a sender approved for US traffic is not automatically evidence for an EU destination.
The third invariant is a failure boundary. “Accepted” means an upstream service accepted a handoff. It does not mean the carrier delivered the SMS or that a person read it. Model those states separately: created, queued, accepted, submitted, delivered, expired, and terminal failure. Keep the raw carrier or route reason beside your normalized class so a later investigation does not lose useful detail.
Keep it finite.
For login verification, add a single active challenge, a short expiry, and a maximum attempt count. OWASP’s forgot-password guidance recommends consistent responses that do not reveal whether an account exists; the same privacy property belongs on an SMS verification endpoint. A transport failure must not become an account-enumeration oracle.
What should a Node.js marketplace notification path record before SMS routing?
The application can be written in Node.js while keeping the transport contract provider-neutral. The order service emits an idempotent event. A worker resolves consent and registration for the destination, renders the final body, computes its signature, and writes an attempt before making an external call. A receipt consumer later reconciles delayed delivery events.
Here is the critical path in Python; the data contract is language-independent and deliberately small:
from dataclasses import dataclass
from datetime import datetime, timedelta
from hashlib import sha256
@dataclass(frozen=True)
class SmsAttempt:
notification_id: str
attempt_no: int
country: str
sender_id: str
body: str
body_signature: str
created_at: datetime
def signature(body: str) -> str:
return sha256(body.encode("utf-8")).hexdigest()[:16]
def retry_at(failure_class: str, now: datetime) -> datetime | None:
if failure_class in {"carrier_policy", "sender_not_registered", "invalid_recipient"}:
return None
if failure_class == "temporary_route":
return now + timedelta(minutes=5)
return now + timedelta(minutes=15)
The sender_not_registered and carrier_policy cases are terminal for that attempt. Sending the same body again does not repair a policy decision; it only adds duplicate traffic. After an operator corrects registration or consent, create a new attempt with a new reason and preserve the old record. That distinction matters when support asks whether the seller missed one alert or received five copies.
The queue must also be idempotent. Use an application idempotency key such as marketplace-order:81472:seller:392:alert:v3, and reject a second creation for the same logical event. The transport worker can retry a timeout, but it cannot safely assume that a timeout means “not sent”; reconciliation must be able to accept a late receipt without creating another attempt. In practice, that means keeping an append-only attempt ledger and a small projection for the support view. The ledger records the request payload hash, queue enqueue time, provider message ID, route, response class, and receipt sequence. The projection can say “waiting for receipt” while the ledger preserves the fact that the upstream accepted the request at 09:14:03. If a receipt arrives after a deploy, the consumer checks the notification ID and attempt number, applies the state transition once, and emits a metric for the delay. That extra join is what prevents a retry button from turning a missing receipt into a duplicate seller alert.
How do US and EU sender registration, signatures, and carrier filtering change the troubleshooting path?
Investigate in a fixed order so an attractive theory does not outrun the evidence. First normalize the destination to an E.164 representation and verify that consent covers transactional order alerts. Next check the country-specific sender registration and sender type. Then compare the stored body signature with the exact submitted body, including whitespace, Unicode normalization, URL host, and template version. Only after that should you interpret carrier or route reasons and delivery receipts.
Signature drift is a common self-inflicted filter signal. A deploy that changes a short URL domain or adds a footer can make a message look unrelated to its approved use case even though the template name stayed constant. Store a redacted destination and a one-way case reference; do not log a full phone number or a complete OTP. For a telehealth login code, never put the code in analytics labels, queue names, or support screenshots.
Split operational views by country, sender identity, route, and failure class. A global delivery percentage can look healthy while one EU country has a registration mismatch. Alert on shifts in terminal-reason distribution: a rise in sender_not_registered belongs to the registration owner, while temporary_route belongs to the transport owner. Attach provider message IDs and receipt timestamps to the attempt, but keep your internal notification ID as the support-facing key.
I once chased a carrier block that was actually a clock bug. The event was created at 09:14:02 UTC, the first attempt at 09:14:03, and the retry worker compared a local timestamp with UTC. It queued a second attempt at the wrong boundary. The carrier response could not reveal that. We normalized timestamps, logged the retry decision, and changed the support screen from phone-number grouping to notification-ID grouping. The next registration review took ten minutes instead of a log hunt.
Your mileage may vary across routes, and I’m not sure a delivery receipt can establish that a person saw a message. It establishes a transport event. Product analytics and support tooling must keep those claims separate.
How should channel failure boundaries shape recovery?
An order alert has a different urgency and retention requirement from a login challenge. Compare channels against the failure boundary rather than against a headline delivery percentage:
| Channel | Useful property | Boundary to document | Good fit |
|---|---|---|---|
| Transactional SMS | Fast attention on a phone | Carrier policy, registration, handset reachability | Opted-in, time-sensitive order changes |
| Email with a signed link | Rich context and an audit trail | Spam filtering, mailbox delay, link expiry | Receipts and escalation details |
| In-app notification | Durable product history | Requires a session or a later app open | Non-urgent status |
| Voice fallback | Alternate reachability | Higher interaction cost and accessibility review | Narrow recovery path |
The rejected option in this record is “send SMS again until delivery is reported.” It conflates a policy block, an invalid recipient, a delayed receipt, and a worker timeout. Permit a retry only for an explicitly temporary route class, after a delay, under a hard cap, with a visible audit entry. A late delivery receipt should close the existing attempt, not trigger another send.
Stick with SMS when the recipient has opted in, registration matches the destination, and the order has clear time value. Add email or an in-app record when the seller needs searchable details, attachments, or durable history. Use voice only for a bounded recovery workflow with accessibility review.
Measure twice.
The catch is ownership. This design is not suitable when a marketplace cannot maintain consent records, country-specific registration, and receipt reconciliation. Change the workflow or channel in that case; tuning retry counts will not fix missing operational responsibility. Promotional campaigns also belong on a separate, consented program with its own templates and suppression rules.
For telehealth login verification, make the security policy stricter than the seller-alert policy: expire challenges, rate-limit attempts, invalidate older challenges after success, and keep responses indistinguishable for unknown accounts. A durable order notification may be replayable from its event ledger. A login challenge should be single-use.
Top comments (0)