Short answer: treat a settled payment as an event, put the receipt in a durable queue, try transactional email first, and use SMS only after a defined delivery timeout. Polling is a verification loop, not the delivery mechanism. That distinction keeps a slow status API from holding up checkout.
An online course platform has a very specific promise to keep: once a payment settles, the learner should be able to find a receipt later. Email is usually the richer channel, while SMS is a useful backstop for a short confirmation and a link. The hard part is deciding when “sent” is no longer good enough, then making that decision repeatable during a provider outage, a duplicate event, or a user who has both channels enabled.
Reliability starts before the first API call.
Make the state machine boring.
How should Node.js event notifications handle transactional email, SMS fallback, and delivery polling?
-
Separate the payment event from delivery work. The payment service records
receipt_id, learner contact preferences, and a content version in one transaction. It then publishes an outbox record. A worker consumes that record and creates one delivery attempt per channel. If the process dies after the email request but before the database update, an idempotency key derived fromreceipt_idprevents a second receipt from being created.
The queue should carry a small, immutable payload rather than a rendered email. Render the receipt from the stored order snapshot, so a later catalog-price change cannot alter an old document. Keep the original event timestamp; it is the clock used for timeout decisions and support investigations.
-
Define delivery states that mean the same thing everywhere. A practical state machine is
queued -> submitted -> delivered, withfailedandexpiredterminal states. “Submitted” means the channel accepted the request. It does not mean a learner saw it. A provider callback can move an attempt todeliveredorfailed; a poller reconciles attempts that have no callback.
Here is a compact TypeScript worker shape. The interfaces are deliberately generic: an adapter can speak SMTP, an email HTTP API, an SMS API, or an in-house gateway without changing the policy code.
type Channel = "email" | "sms";
type DeliveryState = "queued" | "submitted" | "delivered" | "failed" | "expired";
interface Attempt {
receiptId: string;
channel: Channel;
state: DeliveryState;
providerId?: string;
submittedAt?: string;
lastCheckedAt?: string;
expiresAt: string;
}
interface ChannelAdapter {
submit(input: { receiptId: string; idempotencyKey: string }): Promise<{ providerId: string }>;
status(providerId: string): Promise<"submitted" | "delivered" | "failed">;
}
async function processAttempt(attempt: Attempt, adapter: ChannelAdapter) {
if (attempt.state !== "queued") return;
const result = await adapter.submit({
receiptId: attempt.receiptId,
idempotencyKey: `${attempt.receiptId}:${attempt.channel}`,
});
await saveAttempt({
...attempt,
state: "submitted",
providerId: result.providerId,
submittedAt: new Date().toISOString(),
});
}
async function saveAttempt(attempt: Attempt): Promise<void> {
// Replace with a transaction that also appends an audit record.
}
-
Make fallback a policy, not a catch block. A network exception is not proof that email failed; retry it with bounded exponential backoff. Fallback should happen when the email attempt reaches
failedorexpired, and only when the learner has consented to transactional SMS and a verified phone number is present. Store the reason, such asemail_expired, on the SMS attempt. That gives support staff an explanation instead of a mysterious text message.
The catch is that SMS is a poor receipt document. Keep the message short, avoid sensitive line items, and link to an authenticated receipt page. Do not send both channels merely because both requests succeeded; that creates noise and can look like a duplicate charge. A per-receipt decision record makes this rule testable.
What does delivery polling actually prove?
Polling proves that a remote system reports a state at a particular time. It cannot prove inbox placement, handset visibility, or that the learner opened the message. Use webhooks where available, then poll only the submitted attempts that have not changed. A five-minute deadline for an email receipt might be reasonable for one platform and wrong for another; your support data should set it, and I'm not sure any generic default survives every region or provider.
Use jitter so thousands of course purchases do not poll on the same second. Stop after the expiry time, record the final observation, and let a scheduled reconciliation job catch records whose worker never ran. The poller must be read-only with respect to content: it updates state and timestamps, never re-sends a message.
A useful dashboard separates channel health from learner outcome. Track submission latency, callback latency, poll age, terminal failure rate, and fallback rate by template version and region. Alert on a change in fallback rate, not just on total message volume. A quiet week can hide a broken callback path.
4. Where do standards and failure modes change the design?
Authentication and deliverability are part of reliability. Publish SPF and DKIM records for the sending domain, and set a DMARC policy that matches the domain used in the visible From address; RFC 7489 describes how receivers evaluate that alignment. Keep unsubscribe handling separate from transactional receipts, and maintain a suppression list so a hard bounce does not trigger an SMS surprise.
For account recovery or high-impact enrollment changes, SMS may be an authenticator rather than a notification. NIST SP 800-63B treats SMS-based out-of-band secrets as a constrained option, so do not quietly reuse a receipt text as proof of identity. Give the learner a clear support path when the phone number is stale.
The failure modes worth rehearsing are mundane: the outbox row is written twice, the provider accepts a request and the worker times out, a callback arrives before the submit response is stored, and a user changes contact preferences mid-flight. Idempotent writes, monotonic state transitions, and an append-only audit trail handle these cases better than another retry loop. Test those races with fake adapters before you test message wording.
I would run one deliberately ugly rehearsal before launch: submit receipt ed-1842, kill the worker after the gateway acknowledges it, deliver the same payment event twice, and then inject a “delivered” callback before the submit response is committed. The database should end with one email attempt, no duplicate SMS, and an audit trail that explains each transition. If the callback is lost, the poller should reach the same terminal state; if the phone consent was revoked while the email was pending, the fallback decision should be skipped, not a surprise text. This test takes longer to write than a happy-path unit test, but it catches the exact race that creates duplicate receipts during a busy enrollment window.
5. How can you compare channel providers without locking the application?
Compare adapters on observable contracts: idempotency support, callback authenticity, status vocabulary, regional coverage, retention of message metadata, and rate-limit behavior. Amazon SES, SendGrid, and Twilio expose different combinations of email and messaging workflows; their APIs and event terminology are not interchangeable, so keep those details behind the ChannelAdapter boundary. A self-hosted SMTP relay can reduce dependency on an HTTP API, but it transfers queueing, reputation, and operations work to your team.
| Approach | Integration surface | Good fit | Main trade-off |
|---|---|---|---|
| SMTP relay | SMTP plus your own status store | Teams already operating mail infrastructure | You own reputation, retries, and delivery telemetry |
| Email API + SMS API | Separate REST adapters | Independent channel policies and failover | Two contracts and two callback systems to reconcile |
| Unified messaging API | One provider contract | Small teams that value a single integration | Switching channels or vendors may require adapter work |
Do not make price the deciding metric. Count engineering time, template migration effort, incident response, and the cost of duplicate or missing receipts. A vendor with a broad API surface can still be a poor fit if its status events cannot be correlated to your receipt_id.
Stick with a single channel when the receipt is non-urgent, the learner has no SMS consent, or your legal review prohibits a link in text messages. Choose a second channel when the business consequence of a missing receipt is higher than the privacy and support cost of an extra contact path. That is a product decision, not an automatic property of Node.js.
6. The operational checklist I would ship
Before enabling the worker, replay a settled payment and verify one outbox record, one email attempt, and one audit trail. Kill the process after submission, deliver a duplicate event, and inject a callback before the database commit. Confirm that each test ends with one receipt decision and that a late callback cannot resurrect an expired attempt.
Then measure it in production with redacted identifiers. Retain enough metadata to answer “which template, which channel, which state transition?” without retaining message bodies or card data. Review the timeout and fallback rates monthly; your mileage may vary as carriers and learner behavior change.
The simplest reliable implementation is a boring one: durable event, idempotent adapter, explicit states, bounded polling, and a fallback rule that a reviewer can read in one screen. That gives an edtech team room to change providers later without rewriting payment logic.
References
- https://datatracker.ietf.org/doc/html/rfc7489
- https://pages.nist.gov/800-63-3/sp800-63b.html
- https://developer.mozilla.org/en-US/docs/Web/HTTP/Status
- https://aws.amazon.com/ses/
- https://sendgrid.com/en-us/solutions/email-api
- https://www.twilio.com/docs/messaging
Top comments (0)