Node.js Compliance Notices: Auditing Transactional Email and SMS via API Polling

#email #node #architecture

A Node.js event-notifications service for e-commerce must distinguish a transactional email request from delivery evidence before it can justify an SMS fallback. An accepted API request is only the beginning of that audit.

Short answer: use transactional email as the primary channel, poll for delivery events, and let a durable Node.js policy engine authorize SMS fallback at a recorded deadline. This is a sound choice only when pull-based tracking fits the notice window; if delivery state must arrive by webhook within seconds, choose a provider that documents that contract.

The architecture decision is therefore about delivery reliability, not message composition. Store a compact transition ledger as the durable proof, keep polling outside the web process, and treat an absent event as unknown rather than failed. That's the boundary that prevents a temporary lack of evidence from turning into an unnecessary text message.

How do Node.js event notifications govern transactional email and SMS polling?

Four invariants carry most of the design. First, one business notice ID follows the workflow across channels and retries. Second, a worker records the escalation decision before it sends the fallback. Third, repeated event pages produce the same normalized transition. Fourth, SMS cannot leave the application until consent, geography, country-spend, and anti-abuse policy checks pass. Keep accepted, delivered, unknown, and terminal separate; collapsing them into sent: true makes an audit easy to store and hard to defend. The application should retain the notice ID, policy version, channel, provider message ID, normalized state, observation time, attempt number, and a digest of the original payload. Recipient email addresses and phone numbers don't belong in metric labels. They belong in access-controlled business records with explicit deletion rules. The failure boundaries are also concrete: email and SMS delivery tracking on the unified REST option is pull-only, so the application owns polling schedules, retries, and cross-channel coordination; there is no SMTP relay for reusing a legacy mailer; scheduled email cannot be canceled, while SMS has a cancellation operation; email has no managed OTP operation; and voice, WhatsApp, and RCS are outside this channel set. A pending Tencent email vendor is not evidence of domestic-China compliance readiness. One race remains: email may be delivered after the final poll but before the SMS request. An atomic sms_committed transition prevents two workers from issuing the same logical fallback, but it cannot close that cross-channel observation gap. The policy owner must decide whether a duplicate notice is less harmful than a missed deadline. For a legal notice, that answer may be yes. For a high-volume promotional stream, it probably isn't.

Unknown stays unknown.

How do four notification contracts compare against one audit ledger?

The useful comparison asks who owns orchestration, how many product contracts the team operates, and whether pull-based evidence meets the deadline. Account-level availability and current regional terms still need procurement verification.

Candidate	Operational boundary	Sensible fit	Choose something else when
AWS SES plus Amazon SNS	Two channel services behind an application-owned ledger	The organization already operates its notification controls in AWS	A two-service integration is too much surface for this workflow
Twilio SendGrid plus Twilio Messaging	Separate email and messaging products under one policy engine	Channel-specific product tooling matters more than a uniform API	The team wants one request convention across both channels
Postmark plus a selected SMS provider	A focused email service paired with a separately procured text service	Email specialization is the primary decision factor	Two credentials, schemas, and billing relationships create unwanted operational work
Infrai	Plain REST for both channels, with no SDK or client-library lifecycle, plus one key and one bill	A language-neutral HTTP boundary is more valuable than push events	Pull-only tracking, no SMTP reuse, or absent voice, WhatsApp, and RCS channels violates a hard requirement

None of these choices removes the application ledger. The first three compositions can be better when an existing operating model, procurement agreement, or channel-specific requirement outweighs interface uniformity. The fourth reduces client integration surface, but the catch is substantial: scheduled polling, escalation policy, consent checks, geographic controls, country spending stops, and abuse throttles remain backend responsibilities.

Cost attribution also stays local because the unified option has no cost-report API grouped by tag. This is where a small data model earns its keep: record bounded channel and notice-type dimensions with each transition, then aggregate from the ledger rather than attaching unbounded recipient data to telemetry.

Curl marks the escalation boundary

The code boundary can remain small even though the state machine cannot. The following commands begin after the primary email request has been accepted. email-events.json is the evidence input; sms-fallback.json must be generated and validated from the live discovery schema before this worker runs. The notice ID is stable across retries.

curl --silent --show-error --fail-with-body \
  --request GET \
  --url "${COMM_API_ORIGIN}/v1/email/event/list" \
  --header "Authorization: Bearer ${INFRAI_API_KEY}" \
  --retry 4 \
  --retry-all-errors \
  --retry-max-time 60 \
  --output email-events.json

curl --silent --show-error --fail-with-body \
  --request POST \
  --url "${COMM_API_ORIGIN}/v1/sms/send" \
  --header "Authorization: Bearer ${INFRAI_API_KEY}" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: ${NOTICE_ID}" \
  --data-binary "@sms-fallback.json" \
  --retry 4 \
  --retry-all-errors \
  --retry-max-time 60

Both calls declare the method, surface a non-success response body, and use bounded retry behavior. Curl honors Retry-After when the server supplies it. The idempotency key protects the write during retries, but it does not replace the database transition: parse and validate the event response, associate it with the stored provider message ID, and commit sms_committed before executing the second command. One poll with no matching event is not permission to send an SMS.

The sample deliberately avoids undocumented query parameters and payload fields. That is less visually satisfying than a large JSON object, but a copied field invented by an article is a reliability defect. The public discovery surface exposes the current request JSON Schema and runnable examples, so deployment checks can validate sms-fallback.json against the actual contract. Set COMM_API_ORIGIN to the documented API origin in the worker environment; keeping it outside the article also makes the deployment boundary explicit.

Polling cost means fan-out, cardinality, and retention

A fixed interval looks simple and produces waste in exactly the place observability teams tend to ignore. With 60,000 notices awaiting evidence, polling every 15 seconds schedules 4,000 reads per second before retries. Logging one routine success record per read then creates a storage problem that says little about delivery quality.

Use a graduated schedule instead: check at 15 seconds, 45 seconds, 2 minutes, and then 5 minutes until the policy deadline. Those values are design examples, not measured provider latency. I'm not sure there is a universal cadence; the correct inputs are the legal deadline, the observed delivery distribution in your own system, and the tolerated chance of sending both channels.

Cardinality needs the same discipline. Six bounded notice types multiplied by two channels, four normalized states, and three regions yield 144 label combinations before infrastructure labels. Add 500,000 recipient identifiers and the metric becomes an expensive lookup table. Don't do that. Keep bounded dimensions in metrics, sample routine poll logs once the path is established, retain unresolved and terminal transitions at full fidelity for the investigation window, and preserve the compact ledger for the compliance retention period.

Noisy polls are not proof.

A worker should claim durable next_check_at records, add jitter so a batch does not wake on one second, and replay overdue work after a restart. On HTTP 429, it should honor Retry-After and apply bounded exponential backoff. Immediately before SMS escalation, it should perform one final email-event read, atomically record the decision, and issue the idempotent fallback. This sequence spends telemetry on decisions rather than on heartbeat-shaped reassurance.

Reliability stops at the push-event deadline

Webhook-first is the rejected design for this API boundary because both tracking surfaces are pull-only. It is still the right design when the escalation decision must follow a delivery event within seconds. Stick with a provider that documents suitable webhooks in that case, authenticate inbound events, deduplicate them, persist every normalized transition, defend against replay, and retain a periodic reconciliation job for missed callbacks.

SMTP-first also has a valid use case. If a mature mailer already satisfies the audit and retention requirements, preserving it and adding a separate SMS provider can carry less migration risk than replacing a trusted boundary for API uniformity. The resulting composition is less tidy. Reliability engineering doesn't award points for tidiness.

The final decision rule is narrow: choose email with SMS fallback when scheduled polling meets the compliance deadline, the application can own the state machine, and the required channels end at email and SMS. Choose a different contract when webhooks, SMTP reuse, managed email OTP, domestic-China readiness, voice, WhatsApp, or RCS is mandatory. If cancellation before release is required, hold an email in the application's durable queue and call the send operation only when the delay expires; don't schedule it remotely and assume it can be withdrawn.

DEV Community