Critical Outage Alerts: Choose an SMS API by Polling Delivery Status

Short answer: choose the SMS API whose delivery evidence can be normalized into your own small state machine, retained under a documented policy, and tested independently of its dashboard. For an edtech system that generates a report, attaches it to an email, and pages an operator when that pipeline fails, polling, retry, resend, and cancel matter only after the team defines what each transition proves. A provider's delivered label is evidence about the SMS leg; it doesn't prove that an operator read the alert or that the report email recovered.

That distinction sets the architecture. The report pipeline should emit a failure event, a Node.js alert service should own the message record and idempotency key, and an adapter should translate the selected API's statuses into a deliberately small internal vocabulary. Keep the raw response for a bounded audit window, but don't make every provider field a permanent metric label. Compliance evidence is useful. Unbounded cardinality is a bill.

What delivery status should an SMS API expose for critical outage alerts?

Start with an evidence matrix, not an endpoint demo. The relevant question is whether an API exposes enough information to reconstruct a message's lifecycle without treating a mutable dashboard as the system of record. Ask each candidate for documented status meanings, terminal states, timestamps, webhook authentication, polling behavior, retention, regional processing terms, and the exact boundary of cancellation. Then verify those answers in a sandbox and in a contract test.

For this workload, the unit of analysis is an alert attempt tied to one failed report job. It isn't a phone number and it isn't a free-form log line. A useful internal record contains an opaque report_job_id, an alert_id, an attempt, the provider's message identifier, the normalized state, the raw provider state, and timestamps for accepted and terminal transitions. The report itself, student name, email address, attachment name, and SMS body don't belong in telemetry. They increase exposure without helping an engineer answer whether an alert was submitted or delivered.

The catch is that the candidate with the richest event stream can be the wrong choice for a small team if operating that stream requires queues, signature rotation, replay handling, and a high-cardinality observability model the team cannot sustain. A polling-only integration can be reasonable for low alert volume and a generous notification deadline. Stick with an existing incident paging path when the organization needs acknowledgement, escalation, and schedules rather than a bare SMS transport. An SMS API is not an incident-management system.

I'm not sure any public feature page can settle the regional compliance decision on its own. The missing evidence is contractual: where message metadata is processed, which subprocessors participate, how deletion works, and what the provider will attest. Security and legal reviewers need those answers before implementation, not after a production payload has crossed a boundary.

Retention policy precedes the state model

Normalize aggressively. A compact state machine might use created, accepted, delivered, undeliverable, canceled, and unknown. Provider-specific intermediate labels can remain in the audit event while metrics use the normalized state. This preserves diagnostic evidence without turning every spelling change into a new time series.

Keep unknown honest.

An accepted request may later become delivered or undeliverable. A polling timeout is not a delivery failure; it means the observer lacks current evidence. Likewise, cancellation is conditional. The alert service can request cancellation while a message is still eligible, but it should record the provider's resulting state rather than rewriting history to canceled as soon as the request begins. These rules prevent optimistic dashboards from becoming compliance claims.

Retries are not resends. A retry repeats an operation whose outcome is unknown, using the same idempotency scope when the API supports it. A resend creates a new attempt after a known terminal outcome or an explicit operator decision. The second action needs a fresh provider message ID and an attempt value of 2, while retaining a link to attempt 1. Without that distinction, one harmless transport retry can look exactly like two intentional pages during an audit.

For a generated report outage, I would make the event boundary explicit: report.email.failed may create an alert, while report.email.recovered may suppress a queued alert or close the incident record. DKIM, defined by RFC 6376, authenticates a domain-level signature on the email message; it is relevant evidence for the email leg, but it doesn't certify attachment generation, mailbox placement, or human receipt. The SMS record should point to the failed report job through an opaque identifier, not copy the attachment or its educational data.

The Node.js application should also own a provider-neutral error taxonomy. For example, ALERT_INPUT_REJECTED is permanent until input changes, ALERT_STATE_UNKNOWN permits bounded observation, and ALERT_UNDELIVERABLE permits a policy decision about a new attempt. HTTP status alone is too coarse for that decision, and logging an entire response body merely moves sensitive data into a second storage system.

A Node.js boundary for message side effects

A local facade keeps business policy out of the provider adapter. The following calls are contract tests against an illustrative Node.js service running on the developer's machine; they are not claims about a commercial API. The first request creates one alert for a failed report job. The idempotency key is derived from the job and policy version, so a client retry doesn't silently create a second logical alert.

curl --request POST \
  --url http://localhost:3000/alerts \
  --header 'content-type: application/json' \
  --header 'idempotency-key: report-job-8421-policy-3' \
  --data '{
    "event_type": "report.email.failed",
    "report_job_id": "job_8421",
    "recipient_ref": "oncall_primary",
    "region_policy": "eu"
  }'

The response should expose the local alert ID and normalized state. Callers poll that local resource, not a provider-shaped object, which lets an adapter change without forcing the report service to learn a new status vocabulary.

curl --request GET \
  --url http://localhost:3000/alerts/alt_01J7Q9K2

Resend and cancel are commands with preconditions. A resend creates another attempt under the same logical alert; cancel asks the adapter to stop an eligible attempt. Returning 409 Conflict for an invalid transition, such as trying to cancel a terminal delivery, makes the race visible without pretending that the SMS was recalled.

curl --request POST \
  --url http://localhost:3000/alerts/alt_01J7Q9K2/resend \
  --header 'content-type: application/json' \
  --data '{"reason":"operator_requested"}'

curl --request POST \
  --url http://localhost:3000/alerts/alt_01J7Q9K2/cancel \
  --header 'content-type: application/json' \
  --data '{"attempt":2}'

This contract is intentionally narrow. It leaves phone-number resolution, quiet-hour rules, and escalation policy on the server, where they can be reviewed. It also gives an agent-generated tool call a constrained schema rather than access to a raw messaging API. Anthropic's tool-use guide describes tools through names, descriptions, and input schemas; regardless of which model invokes the action, validate every field and authorization decision in the Node.js service. A model choosing a tool is not evidence that the send was permitted.

Don't retry forever. Set a deadline from the operational objective, cap attempts, add jitter, and stop on permanent input failures. The precise numbers depend on the provider's documented limits and the school's escalation policy, so a universal interval would be false precision. What matters is that the policy is deterministic, observable, and unable to turn one report failure into an SMS storm.

Cost follows audit bytes and metric cardinality

Delivery evidence has a storage shape, and the shape is calculable before launch. Suppose a planning model uses 20,000 report failures per month, two SMS attempts per failure, six audit events per attempt, and an average serialized event size of 900 bytes. That is 216,000,000 bytes per month before indexes, replicas, and backups. These are illustrative inputs, not benchmark results; replace every value with a measured value from the sandbox. The formula is simple: failures times attempts times events times bytes. Retention multiplies the result. If the audit requirement is 13 months, keeping all raw events online produces a very different cost and exposure profile from keeping 30 days searchable and archiving the required subset under a controlled retention policy. Decide which fields establish compliance evidence, document deletion behavior, and test that deletion. “Keep everything” is not neutral risk management. Metrics need an even tighter budget. Good dimensions include normalized state, adapter, region policy, and attempt bucket. Bad dimensions include message ID, report job ID, recipient reference, phone number, error text, and attachment name. Those belong in access-controlled audit storage if they belong anywhere. A counter with message_id as a label creates roughly one time series per message, so sampling log bodies won't repair the metric cardinality mistake. Sampling also changes what can be proved. Sample verbose success diagnostics if aggregate counters and the authoritative audit record remain complete; don't sample the terminal event that the compliance workflow relies on. Keep full error evidence only as long as policy requires, redact payloads before ingestion, and measure bytes after serialization because that is what storage and transfer systems actually receive. The cheap-looking API can produce the expensive integration when each transition fans out into logs, traces, metrics, archives, and duplicated regional stores.

This is where candidate comparison becomes concrete. Run the same scripted scenario through each adapter: accepted then delivered, accepted then undeliverable, lost webhook followed by polling, ambiguous submission followed by retry, resend after a terminal state, and cancel racing an in-progress attempt. Score the evidence returned, the amount of adapter-specific code, and the telemetry volume. Don't score dashboard screenshots.

Test the migration with explicit exit criteria

Begin with recorded fixtures for every normalized transition, then run sandbox sends to test signatures, polling convergence, duplicate control, and cancellation semantics. Deploy the adapter in shadow mode so it consumes report-failure events and writes proposed actions without contacting recipients. Compare those actions with the existing alert path, especially around repeated events and recovery races.

Move a small, non-sensitive on-call cohort only after the team can reconcile local alert records with provider evidence. The rollout gate should include zero unexplained duplicate logical alerts, bounded unknown states, verified retention deletion, and a tested fallback path. Your mileage may vary on the observation window because outage frequency and staffing differ, but the exit criteria should be written before traffic moves.

Not suitable when SMS itself must provide human acknowledgement or multi-step escalation. In that case, keep the richer paging workflow and treat SMS as one transport inside it. For the edtech report-email pipeline, the sound choice is the API that fits the evidence contract with the least status translation and a telemetry footprint the team has intentionally priced, retained, and constrained.

References

• https://datatracker.ietf.org/doc/html/rfc6376
• https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview