Short answer: choose an SMS alerts API only after its delivery events can be turned into a durable, queryable compliance record; the API call is the easy part, and the evidence boundary is where systems usually fail.
For a media SaaS sending a rights-expiry or takedown notice, I would model one notification as an append-only case with four stages: intent, provider acceptance, handset outcome, and recipient suppression. That decision keeps a reviewer from confusing “we sent a request” with “the notice was delivered,” while still allowing a Node.js service to swap transport providers later.
What should a SaaS SMS alerts API record for US and EU delivery?
Start with an internal notice_id, not the provider message ID. Store the tenant, recipient purpose, legal basis, template revision, locale, destination country, and scheduled time before making a network call. The initial row is an intent; it is not proof of delivery.
The transport adapter then records the provider's acceptance response and its correlation ID. A webhook or delivery-status polling job adds later observations, each with an event timestamp and the source payload hash. Polling is useful when a webhook is delayed, but it must be idempotent: the same status observed three times is still one state transition.
That distinction is easy to miss.
Cancellation has a narrow meaning. It can prevent a queued message from leaving the transport, yet it cannot retract a handset notification that already reached the network. The audit record should therefore preserve the cancellation request, its time, and the last known delivery state instead of rewriting history.
Suppression is a policy decision, not a transport error. Keep opt-outs keyed by tenant and purpose, apply them before scheduling and again before dispatch, and retain the rule version that caused a send to be skipped. RFC 8058 describes one-click unsubscribe for email, not SMS, but its central evidence idea still applies: record an explicit user action and the system response separately.
The evidence pipeline and its failure boundaries
I use a small state machine because a pile of boolean columns hides impossible combinations. A message can be accepted and later fail; it cannot be “delivered” merely because a request returned HTTP 200. Here is the critical path in Python, with a generic HTTP adapter behind it:
from dataclasses import dataclass
from datetime import datetime, timezone
@dataclass(frozen=True)
class Event:
notice_id: str
kind: str
occurred_at: datetime
payload_sha256: str
def record_acceptance(store, notice_id, provider_id, raw_payload):
event = Event(
notice_id=notice_id,
kind="accepted",
occurred_at=datetime.now(timezone.utc),
payload_sha256=sha256(raw_payload),
)
store.append(event, provider_id=provider_id)
def apply_delivery_observation(store, event):
allowed = {"accepted", "queued", "delivered", "failed", "cancelled"}
if event.kind not in allowed:
raise ValueError("unrecognized delivery state")
store.append(event) # append-only; a later event never edits an earlier one
The adapter should expose a stable internal contract such as send_notice, poll_status, and cancel_scheduled. Its implementation may call different vendor APIs, but the application sees the same event vocabulary. Keep raw responses encrypted with a retention period that matches the legal review window; hashes and normalized fields remain searchable after payloads expire.
Three failure modes deserve explicit tests. First, a timeout after submission can produce a duplicate unless the idempotency key is the notice ID. Second, a webhook race can make a cancellation appear newer than delivery unless ordering uses provider timestamps plus a deterministic tie-breaker. Third, a template edit can make an old message impossible to reconstruct unless the rendered body or immutable template revision is retained. In one review I would walk the timeline minute by minute: the worker submits at 10:00:02, the socket times out at 10:00:12, a retry starts at 10:00:14, and the first acceptance arrives at 10:00:17; without a stable key, two notices can be legally indistinguishable in the log even though only one should exist. The audit question is not whether the retry felt safe. It is whether the record can prove which attempt created the notification.
Keep this state machine boring.
Trade-offs I would put in the decision record
| Choice | Helps with | Cost or boundary |
|---|---|---|
| Webhooks as the primary status feed | Low latency and fewer reads | Requires signature verification, replay protection, and a retry ledger |
| Polling as the primary feed | Simple firewall model and predictable control loop | Adds delay, rate-limit pressure, and a terminal-state timeout policy |
| Provider-hosted templates | Centralized approvals and locale management | Couples evidence to a vendor revision format; exportability must be tested |
| Rendered text in your own store | Exact reconstruction for an audit | More sensitive data at rest and a stricter deletion workflow |
| One regional sender pool | Fewer operational knobs | May conflict with local sender rules or data-residency commitments |
The rejected option here is “send, then keep only the API response.” It is acceptable for a low-stakes product hint, where delivery evidence is not part of the requirement. It is not suitable for a compliance notice because acceptance, delivery, suppression, and cancellation become indistinguishable months later.
How do polling, cancellation, templates, and suppression fit a Node.js service?
Keep scheduling and evidence storage in your service, even when a transport offers a convenient scheduler. A worker claims due notices, checks suppression, submits with an idempotency key, and records acceptance in one transaction boundary. A separate poller reads only non-terminal notices and stops after a documented horizon; “unknown” is a review state, not a success state.
For Node.js teams, the useful test is not whether an SDK exists. It is whether the raw HTTP contract, retry semantics, and status vocabulary are documented well enough to implement a small adapter in Python or JavaScript without hidden side effects. I prefer a contract test that replays accepted, delayed, failed, and cancelled fixtures, then checks that every transition leaves an immutable event.
Apple's Mail Privacy Protection guide is a reminder that client-side signals can be distorted; SMS has its own carrier and handset gaps. Delivery receipts are evidence from a network path, not proof that a human read the notice. Your policy should say exactly what each state proves and who may override an unknown result.
Pick the simplest API that supplies signed or verifiable status events, an idempotency mechanism, scheduled-message cancellation semantics, and exportable template/suppression data. Do not select on price alone; a low call rate does not repair an evidence model that cannot answer an auditor's “what happened, when, and why?”
The catch is that a single transport may not fit every jurisdiction, sender type, or retention policy. Stick with a direct carrier integration when regional control is the primary constraint, and accept the additional operational burden. Use a multi-provider adapter when continuity matters more than a single control plane, but budget for reconciliation and duplicate prevention. I'm not sure any status API can establish human receipt; your mileage may vary, so document that limit rather than implying certainty.
Top comments (0)