Short answer: For SMS event notifications, troubleshoot resend failures before retrying: verify carrier filtering, sender registration, jurisdiction, content, and the latest delivery evidence. For a media company sending a compliance notice, the system must preserve what it tried, why it tried again, and what the downstream system actually confirmed without turning an acceptance response into a claim that a handset received the message.
That changes the build. A generic retry queue is useful for transient transport trouble, but it can't decide whether carrier filtering, sender registration, message content, or recipient state made the original attempt non-retryable. Blind retries can repeat the same bad input and muddy the audit record.
Ship the classifier first.
The working rule is seven checks before resend: recipient and consent state, jurisdiction, sender identity, registration state, message signature or template, provider response class, and the latest delivery event. Store each decision as an append-only attempt linked to the notice. If any required fact is unknown, hold for review instead of guessing. I'm not sure a universal retry delay exists across carriers and jurisdictions; the evidence needed to resolve that belongs in current carrier and provider policy, not in a hard-coded folklore value.
How should US and EU SMS event notifications handle carrier filtering?
Start by separating three events that dashboards often compress into one word: submitted, accepted, and delivered. A downstream acceptance is evidence that the downstream system accepted the request. It isn't proof of delivery, reading, or legal notice. The delivery event can arrive later, and some systems may never supply a terminal handset event. Your audit model needs to retain that uncertainty rather than rewrite history.
Then classify the latest known result before scheduling anything. A transport interruption can justify a bounded retry. A deterministic policy rejection should be held until its input changes. A carrier-filtering signal should trigger content, sender, registration, and jurisdiction review. An explicit recipient opt-out should stop the workflow. These are decision categories for your own system, not promises about any provider's exact status vocabulary. Map provider-specific responses into them at the adapter boundary and retain the raw response beside the normalized value.
The seven checks form a compact runbook:
- Confirm the destination is the intended recipient and that the notice is allowed to use this channel.
- Resolve the destination's jurisdiction from maintained account data and routing metadata; don't infer policy from a country prefix alone.
- Select the sender identity configured for that jurisdiction and message class.
- Verify the sender's registration state in the configuration snapshot used for this attempt.
- Validate the exact rendered body, including any required sender signature, template variables, URL, and opt-out text.
- Normalize the immediate response while preserving its raw code and body.
- Read the newest delivery event, then choose retry, hold, alternate channel, or stop.
No guesswork.
A signature deserves special care because the word is overloaded. It might mean visible text identifying the sender, a registered template element, or a cryptographic request signature between services. Record those as separate fields. If one Boolean called signatureValid covers all three, an operator can fix the wrong layer and confidently resend the same rejected message.
US and EU routing shouldn't share a single assumed registration rule. Keep jurisdiction policy in versioned configuration, with an owner and review date, because the application needs to show which rule set made the decision. Exact registration and sender requirements must be checked against the current carrier, provider, and legal guidance for the route in question. Your mileage may vary by message class and destination.
Data governance for an auditable notice
The notice is the business object; an SMS is only one delivery attempt. That distinction sounds small, yet it determines whether the audit log survives retries and channel changes. Model one immutable notice, one rendered artifact per channel, and many attempts. Every attempt points to the exact policy version and content digest it used. A later correction creates another artifact or attempt. It never edits the old row.
For an indie SaaS, this is a revenue-per-hour choice. Building a carrier rules engine from scratch can consume weeks that should go into the product, while outsourcing delivery doesn't outsource the obligation to understand your own evidence. Keep the narrow control plane that differentiates the workflow: notice identity, policy decision, content version, attempts, and audit export. Put commodity transport behind a small adapter. Ship weekly, but don't ship an evidence model that treats mutable application logs as the legal record.
Email is a useful warning from the neighboring channel. Yahoo's published sender guidance distinguishes authentication, easy unsubscribe, complaint rates, and delivery practices rather than presenting deliverability as one retryable switch. The transport differs, but the design lesson carries: sender identity, recipient choice, content, and delivery evidence are separate concerns. OWASP's forgot-password guidance makes a parallel security point for one-time codes: responses should avoid account enumeration, codes should be random, stored securely, single use, and expire. If the compliance notice contains a login or recovery action, the resend path must not weaken those controls.
The catch is retention. An append-only audit trail improves explainability, but retaining full message bodies and raw provider payloads can increase exposure. Store only the evidence the compliance use case needs, redact secrets, define retention by data class, and keep a content digest when the body itself doesn't need long-term storage. This is a design decision requiring legal and security review, not a universal number copied from a blog post.
Implementation: the smallest useful delivery record
The smallest implementation has two boundaries: a transport adapter and an evidence store. It also has a pure decision function, which makes policy tests cheap. No SDK type or vendor status leaks into the domain.
type AttemptState =
| "queued"
| "accepted"
| "delivered"
| "rejected"
| "unknown";
type Decision = "send" | "retry" | "hold" | "alternate" | "stop";
interface Notice {
id: string;
recipientId: string;
jurisdiction: "US" | "EU" | "other";
contentDigest: string;
policyVersion: string;
}
interface DeliveryAttempt {
id: string;
noticeId: string;
previousAttemptId?: string;
channel: "sms" | "email";
senderProfileId: string;
registrationSnapshotId: string;
state: AttemptState;
reason: string;
rawResponseRef?: string;
createdAt: string;
}
interface TransportResult {
state: "accepted" | "rejected" | "unknown";
externalId?: string;
rawResponse: unknown;
}
interface SmsTransport {
send(input: {
destination: string;
senderProfileId: string;
body: string;
idempotencyKey: string;
}): Promise<TransportResult>;
}
interface EvidenceStore {
append(attempt: DeliveryAttempt): Promise<void>;
protectRawResponse(attemptId: string, value: unknown): Promise<string>;
}
The resend function should receive a completed policy evaluation rather than silently recompute policy from whatever configuration happens to be live. That gives the audit exporter a stable answer to “why did the system send this at that time?”
interface ResendReview {
decision: Decision;
reason: string;
senderProfileId: string;
registrationSnapshotId: string;
renderedBody: string;
}
async function executeReviewedSend(
notice: Notice,
previous: DeliveryAttempt | undefined,
review: ResendReview,
destination: string,
transport: SmsTransport,
evidence: EvidenceStore,
now: () => string,
): Promise<DeliveryAttempt> {
const attemptId = crypto.randomUUID();
if (review.decision !== "send" && review.decision !== "retry") {
const held: DeliveryAttempt = {
id: attemptId,
noticeId: notice.id,
previousAttemptId: previous?.id,
channel: "sms",
senderProfileId: review.senderProfileId,
registrationSnapshotId: review.registrationSnapshotId,
state: "rejected",
reason: review.reason,
createdAt: now(),
};
await evidence.append(held);
return held;
}
const result = await transport.send({
destination,
senderProfileId: review.senderProfileId,
body: review.renderedBody,
idempotencyKey: attemptId,
});
const rawResponseRef = await evidence.protectRawResponse(attemptId, result.rawResponse);
const attempt: DeliveryAttempt = {
id: attemptId,
noticeId: notice.id,
previousAttemptId: previous?.id,
channel: "sms",
senderProfileId: review.senderProfileId,
registrationSnapshotId: review.registrationSnapshotId,
state: result.state,
reason: review.reason,
rawResponseRef,
createdAt: now(),
};
await evidence.append(attempt);
return attempt;
}
One detail matters: the held branch above uses rejected because this minimal type describes an attempt outcome. In a production schema, policy disposition and transport state should be separate fields so “not sent after review” can't be confused with “sent and rejected downstream.” That is the first schema change I would make before connecting a real adapter. The small sample exposes the boundary instead of hiding it.
Tests should cover duplicate queue delivery, an opt-out arriving between the first attempt and retry, a registration snapshot changing, late delivery events arriving out of order, and an alternate-channel send. Assert the evidence sequence, not just the final state. A test that only checks delivered === true misses most of the compliance value.
Evaluation at scale: metrics and human review
At higher volume, split intake, policy evaluation, transport, event ingestion, and audit export into independently observable stages. Keep one correlation ID across them. Delivery callbacks may arrive late or out of order, so event ingestion should be idempotent and should preserve provider event time alongside receipt time. The current state can be a projection; the event history remains the evidence.
Add metrics by jurisdiction, sender profile, normalized failure class, carrier or route where available, and content template version. Alert on changes in ratios, not one isolated rejection. Also sample rendered messages in a protected review tool so an operator can see the exact signature and variables without searching raw logs.
Don't automate every hold. Carrier filtering is partly an external policy decision, and a confident classifier can still be wrong when its mapping is stale. Automation is suitable for known transient categories with a strict attempt cap. Keep registration, consent, and ambiguous filtering cases reviewable until the team has current, attributable rules and enough evidence to encode them.
Operational limits and stopping rules
A single delivery provider and one adapter are suitable for a small system when operational simplicity matters more than route control. Multiple providers become reasonable when contractual requirements, jurisdiction coverage, or measured delivery behavior justify the extra reconciliation work. The cost is real: each adapter adds response mappings, callback authentication, event ordering tests, and audit-export cases. Avoid a multi-provider abstraction built only for an imagined migration.
SMS is not suitable when the notice requires rich content, durable recipient access, or evidence that the recipient read and understood it. Use an authenticated inbox or another approved channel for that requirement, and treat SMS as a prompt to visit it. Stick with email when the message needs longer context and the recipient relationship supports it, while applying current sender authentication and unsubscribe guidance. For urgent notices, a channel escalation policy can be better than repeatedly sending identical SMS content into the same filter.
Time isn't evidence.
The stopping rule is plain: never resend because time passed alone. Resend when a recorded policy decision says the cause is retryable, required state is still valid, the attempt cap isn't exhausted, and the new attempt will add useful delivery evidence. Otherwise hold, change the approved channel, or stop.
Top comments (0)