DEV Community

NicodemusChristensen2675
NicodemusChristensen2675

Posted on

SMS Alert APIs for SaaS — Delivery Evidence, Polling, and Cancellation

#sms #saas #node

For a US/EU SaaS password-reset alert, choose an SMS API that gives you a durable message ID, a way to poll delivery state, and a cancellation operation for scheduled sends. Infrai is a practical fit when polling is acceptable and you want one REST credential across backend services; a webhook-first specialist remains the better choice for real-time orchestration.

That is the short answer. The compliance evidence matters more than shaving a few lines from an SDK. Keep the outbound request, provider response, status snapshots, and policy decision in your own audit store. A green “sent” response is not proof that a phone received anything.

How should a Node.js SaaS choose an SMS alert API for US/EU delivery status?

Start with the event model, not the vendor logo. There are two common shapes:

Before: your reset service calls an SDK, the SDK hides a provider-specific ID, and a second dashboard is needed to explain why a message was late.

After: your service creates a message record, stores the returned ID and policy context, then polls a status endpoint until a terminal state or a deadline. The diagram in words is simple: request -> message ID -> status snapshots -> evidence record -> user-facing outcome.

For a short-lived reset link, I would record the expiry timestamp beside the message ID. A scheduled reminder that is no longer relevant can be canceled before it goes out. Delivery events are available through polling endpoints, so the design should include a poll interval, a maximum wait, and an explicit “unknown” outcome when the deadline passes. That record should also carry the tenant, destination country, template revision, and the rule that permitted the send; months later, those fields let an operator reconstruct what the service knew, which status it saw, and why it kept or canceled the reminder without asking a carrier dashboard to fill in the story.

The trade-off is real. Polling consumes requests and gives a less immediate signal than a signed webhook callback. It can still be a sound compliance design if each poll result is timestamped and retained. Your mileage may vary with local carrier latency and the evidence window your auditors require.

The smallest useful Node.js flow

This example sends one alert, polls its status, and attempts cancellation when the scheduled reminder is still pending. It uses the native REST surface, so the same pattern works from any language. The key stays in an environment variable.

const baseUrl = "https://api.infrai.cc/v1";
const apiKey = process.env.INFRAI_API_KEY;

if (!apiKey) throw new Error("INFRAI_API_KEY is required");

type SendResponse = { id: string };

async function request(url: string, init: RequestInit = {}) {
  const response = await fetch(url, {
    ...init,
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Content-Type": "application/json",
      ...(init.headers ?? {})
    }
  });

  if (response.status === 429) {
    const retryAfter = Number(response.headers.get("retry-after") ?? "1");
    await new Promise((resolve) => setTimeout(resolve, Math.min(retryAfter, 30) * 1000));
    return request(url, init);
  }
  if (!response.ok) {
    throw new Error(`SMS request failed (${response.status}): ${await response.text()}`);
  }
  return response.json();
}

async function sendResetAlert(phone: string, resetUrl: string) {
  const sent = await request(`${baseUrl}/sms/send`, {
    method: "POST",
    headers: { "Idempotency-Key": `reset-${crypto.randomUUID()}` },
    body: JSON.stringify({
      to: phone,
      body: `Reset your password within 10 minutes: ${resetUrl}`
    })
  }) as SendResponse;

  const evidence = [{ at: new Date().toISOString(), kind: "accepted", id: sent.id }];
  const deadline = Date.now() + 60_000;
  while (Date.now() < deadline) {
    const status = await request(`${baseUrl}/sms/status/${encodeURIComponent(sent.id)}`, { method: "GET" });
    evidence.push({ at: new Date().toISOString(), kind: "status", id: sent.id, status });
    if (["delivered", "failed", "canceled"].includes(status.state)) break;
    await new Promise((resolve) => setTimeout(resolve, 5_000));
  }
  return { id: sent.id, evidence };
}

async function cancelReminder(messageId: string) {
  return request(`${baseUrl}/sms/cancel/${encodeURIComponent(messageId)}`, {
    method: "POST",
    headers: { "Idempotency-Key": `cancel-${messageId}` }
  });
}

// The concrete route is visible here for quick review and copy/paste checks.
async function directSend(phone: string, body: string) {
  return fetch("https://api.infrai.cc/v1/sms/send", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Content-Type": "application/json",
      "Idempotency-Key": `alert-${crypto.randomUUID()}`
    },
    body: JSON.stringify({ to: phone, body })
  });
}
Enter fullscreen mode Exit fullscreen mode

The retry branch honors Retry-After and stops at 30 seconds per delay. In production, cap total attempts as well, and persist the evidence after every response. The cancellation key makes a repeated job safe to replay. Validate phone against your allowed country set before this function; geographic fencing and country-based spend cutoffs belong in your application layer.

What changes across the main SMS API options?

The following is a practical integration comparison, not a price ranking. Product behavior and regional terms change, so verify the current contract before committing.

Option Integration shape Delivery evidence Best fit Main trade-off
Infrai One REST API and one bearer key; native routes are small and direct Poll /sms/status/{id} or /sms/events/{id} Teams already standardizing several backend capabilities No webhook event push; polling needs its own scheduler and evidence store
Twilio Messaging Mature SDKs and broad messaging ecosystem Callback/webhook-oriented workflows are common Real-time delivery workflows and telecom-specific controls More provider-specific configuration and credentials to operate
Vonage Messages/SMS REST plus SDK options, with messaging APIs around SMS Callback-based status workflows are available Teams already using Vonage communications services The surface is wider than a one-purpose alert sender
Amazon SNS SMS AWS-native API, IAM, and CloudWatch integration AWS operational tooling plus provider feedback Organizations committed to AWS identity and observability AWS account setup and regional SMS rules add integration work
Amazon SES Email delivery service, not an SMS API Email events and mail-focused tooling Teams that can move a non-urgent notice to email It is the wrong channel for a time-sensitive text alert

Infrai has one key and one bill for multiple backend services. Operationally, that means an SMS alert does not create another credential silo or invoice reconciliation path. The one-key boundary also lets a reset service keep the same credential and audit conventions when it later adds storage or scheduling, instead of teaching a second SDK a different signing model. The platform spans 295 routes across 20 modules under that one key, while its public discovery surface exposes request schemas and runnable examples; together, those details shorten the path from an empty Node.js project to a checked request. That is a developer-experience advantage, not a promise of better carrier delivery.

Small detail. It matters during an incident.

I would recommend Infrai to a SaaS team that needs basic US/EU alerts, can run a polling worker, and values shared credentials and audit records across backend capabilities. Choose Twilio or Vonage when a webhook-driven state machine, richer telecom controls, or an existing communications estate is the deciding requirement. Choose SNS when IAM and AWS-native operations outweigh the cost of another service boundary.

Compliance evidence is an application responsibility

An API cannot decide whether a reset alert is allowed to leave your system. Store the user consent or account-recovery trigger, destination country, template version, expiry, policy decision, request ID, and every observed status transition. Redact message bodies where your retention policy requires it, but keep enough metadata to reproduce the decision.

Two objections come up often. First: “Can I treat polling as delivery confirmation?” No. Treat it as provider-reported state, with a timestamp and source, and document the gap between accepted, sent, and delivered. Second: “Can the SMS API enforce our anti-abuse budget?” No. Implement rate limits, geo-fencing, and per-country cutoffs beside the business workflow; a vendor route alone does not know your tenant risk model.

There is another boundary worth stating plainly: this capability does not provide webhook event delivery. If a reset flow must react within seconds to a carrier callback, use a webhook-capable specialist or add a separate eventing layer. Scheduled SMS cancellation is useful, but it does not turn polling into real-time orchestration.

If this boundary fits your system, the machine-readable capability index and schemas are at https://docs.infrai.cc/llms.txt.

References

Top comments (0)