DEV Community: mT41Gzp73rc6

Password Reset Email Architecture: Node.js Token Links, DKIM/SPF, and API Boundaries

mT41Gzp73rc6 — Thu, 03 Sep 2026 00:08:05 +0000

Short answer: keep password-reset state in the Node.js application, send through a transactional email API behind an outbox worker, and make each token link opaque, short-lived, and single-use. Custom-domain authentication with SPF, DKIM, and DMARC protects deliverability, but it does not make an email credential trustworthy; only the redemption transaction can do that.

That separation is the useful architecture decision. Mail transport has retries, scanners, bounces, and rate limits. Recovery state needs deterministic rules. A reset request should therefore create one durable intent and one credential record, while the delivery layer remains replaceable.

Decision record: invariants and failure boundaries

The public endpoint returns the same response for an existing and an unknown address. It validates the request, records an outbox item, and returns. It does not wait for DNS, an API response, or a mailbox. This prevents account enumeration and keeps web latency independent of delivery.

The application owns the token lifecycle. Store a digest of the random token, its purpose, expiry, user reference, and a used marker. Put the raw value only in the URL sent to the recipient. Redemption hashes the submitted value and atomically changes the unused row to used while changing the password. A second click loses that race. No transport callback is allowed to extend token lifetime or mark it valid.

The worker owns rendering and transport. It receives a versioned template name and a constrained variable map, not arbitrary values from a controller. The reset origin comes from an allowlist in deployment configuration, requires HTTPS, and is never copied from request input. Logs carry a request or outbox identifier and a redacted recipient hash; they never carry the token or complete link.

Delivery is evidence, not authority.

Rate limits should cover several signals: account, normalized destination, source IP, and broader traffic patterns. Exact thresholds depend on the abuse model, so I'm not sure a number copied from a consumer app belongs in a workforce system. Your mileage may vary. The important invariant is that throttling does not turn the response into an account-existence oracle.

How should a password reset email flow in Node.js handle API tokens and links?

Treat the reset link as data. Render an escaped HTML attribute and a plain-text alternative from one canonical URL. Do not place an email address, internal user ID, or authorization claim in the query string. A high-entropy opaque token is enough to locate the digest record.

Do not consume a token on the first GET. Mail security scanners and link prefetchers can visit a URL before a person does. Show a recovery page on GET, then consume the token when the user submits a new password. Enforce purpose and expiry at that point, and revoke sessions according to the application's account-security policy. Consider the full sequence: the outbox worker renders a message, the transport accepts it, a mailbox scanner opens the link, and the person follows it several minutes later. If GET consumes the credential, the scanner wins and the person sees an expired-looking recovery flow even though transport did its job. If GET changes nothing, both visits can render the form, but only a valid POST can attempt redemption. Two nearly simultaneous POST requests then meet the atomic database condition; one changes the password and marks the record used, while the other gets the same generic invalid-or-expired result used for any failed credential. The event stream should preserve request, outbox, delivery, and redemption correlation without preserving the secret itself. This one scenario crosses browser behavior, mail security, queue semantics, database concurrency, user messaging, and logging — which is why the token lifecycle cannot be delegated to a template or delivery callback.

Scanner clicks happen.

Template contracts deserve tests. A password-reset template needs the reset URL, expiry wording that matches server policy, and a support route that does not leak account state. Unknown variables should fail rendering in CI. A missing reset_url is a build failure, not a blank link in production.

Retries need identity. A worker replay after a timeout should reuse the outbox item's idempotency key and credential record. Minting another token for every retry leaves several live links in a mailbox and makes incident review difficult. A retry that has no durable record to reference should stop and raise an operational alert instead of silently creating a new credential.

Don't improvise here.

Here is the critical path as a provider-neutral Python contract. A Node.js service can preserve the same boundaries with its transaction, queue, and crypto libraries; the example intentionally does not invent a vendor-specific API method.

from dataclasses import dataclass
from datetime import datetime, timedelta, timezone
from hashlib import sha256
from secrets import token_urlsafe
from typing import Mapping, Protocol
from urllib.parse import urlencode


class ResetStore(Protocol):
    def create(self, *, user_id: str, digest: str, expires_at: datetime,
               idempotency_key: str) -> None: ...


class MailTransport(Protocol):
    def send(self, *, recipient: str, template_version: str,
             variables: Mapping[str, str], idempotency_key: str) -> None: ...


@dataclass(frozen=True)
class ResetCommand:
    user_id: str
    recipient: str
    request_id: str


def issue_reset(command: ResetCommand, store: ResetStore,
                mail: MailTransport, reset_origin: str) -> None:
    raw_token = token_urlsafe(32)
    digest = sha256(raw_token.encode("utf-8")).hexdigest()
    expires_at = datetime.now(timezone.utc) + timedelta(minutes=20)

    store.create(
        user_id=command.user_id,
        digest=digest,
        expires_at=expires_at,
        idempotency_key=command.request_id,
    )
    query = urlencode({"token": raw_token})
    reset_url = f"{reset_origin}/account/recover?{query}"
    mail.send(
        recipient=command.recipient,
        template_version="password-reset-v3",
        variables={"reset_url": reset_url},
        idempotency_key=command.request_id,
    )

Twenty minutes is an example policy value, not a universal best practice. Use a fake clock to test the exact expiry boundary, and make the visible template copy agree with the server. In a real implementation, the store and send operation are coordinated through an outbox transaction; the simplified function shows the contract, not a claim that two independent calls are atomic.

What do custom-domain SPF, DKIM, and DMARC actually guarantee?

Custom-domain setup is a chain of identities, not a single checkbox. SPF authorizes sending infrastructure for a domain. DKIM signs the message with a domain key. DMARC evaluates SPF and DKIM results, checks identifier alignment with the visible From domain, and publishes policy and reporting instructions through DNS. RFC 7489 defines those evaluation and reporting mechanisms.

Verify the exact From domain, DKIM signing domain, and return-path behavior in every environment. A staging sender that shares production identity can pollute reputation and make aggregate reports hard to interpret. Keep a canary message in the promotion gate: confirm the link's hostname, template version, and authentication results before sending real recovery traffic.

Authentication does not solve content or reputation problems. Sudden volume, complaint spikes, malformed MIME, and a broken unsubscribe policy for non-transactional mail can still affect placement. Record provider events as normalized internal events such as accepted, delivered, delayed, bounced, or complained. Alert on distribution changes, not just on a successful API response.

Which delivery boundary should the architecture choose?

The options differ mainly in control and operational load. None transfers ownership of reset validity away from the application.

Boundary	Application owns	Delivery layer owns	Appropriate when	Trade-off
Transactional email API	Token lifecycle, outbox, templates, redemption	Acceptance, transport, delivery events	The team wants a narrow HTTP integration	Provider quotas and webhook semantics need an adapter
SMTP relay	Token lifecycle, queue, MIME, redemption	Relay and onward transport	An organization already operates mail infrastructure	More connection, bounce, and reputation work stays in-house
Self-hosted transfer	The complete recovery and mail pipeline	Nothing outside the team	Direct infrastructure control is mandatory	Highest on-call and deliverability burden

The catch is dependency concentration in the API option: quotas, regional processing, event retention, and incident support become evaluation criteria. It is not suitable when policy requires direct control of mail-transfer infrastructure or an established internal relay is audited and reliable. Stick with that relay when its reputation, bounce handling, and audit controls are already operated well.

Cost belongs after deliverability controls, data handling, regional fit, event quality, and on-call ergonomics. Compare billing against realistic notification and retry volume only after those gates pass. The least expensive request is not useful if the team cannot explain a delivery gap during account recovery.

Rejected option and its valid use case

I reject synchronous send-on-request for the primary web path. It couples user latency to DNS, transport, rate limits, and template rendering. A browser timeout can happen after a message was accepted, causing a second request and an ambiguous retry. The outbox gives one durable intent and one place to apply idempotency.

Synchronous delivery still fits a controlled integration test or an internal tool where the caller explicitly needs a transport result and account enumeration is not a concern. Even there, credential creation and redemption remain application-owned. A fake transport can capture the rendered message, assert the custom domain and template variables, and hand the token to the test without touching a real inbox.

I also reject using SMS WebOTP as a transparent substitute for an email reset link. MDN describes WebOTP as a browser API for receiving a specially formatted one-time password from an SMS message, with user consent in a secure context. It can support an SMS verification flow, but it changes channel, browser support, consent, and abuse assumptions. Make that a separate decision.

The acceptance record is short: neutral responses, single-use application state, validated reset origin, versioned templates, aligned SPF/DKIM results evaluated through DMARC, idempotent outbox delivery, normalized events, and race-tested redemption. Those checks matter more than a feature matrix.

References

RFC 7489: Domain-based Message Authentication, Reporting, and Conformance (DMARC): https://datatracker.ietf.org/doc/html/rfc7489
MDN Web Docs: WebOTP API: https://developer.mozilla.org/en-US/docs/Web/API/WebOTP_API

Simplest Email Deliverability Service for Small SaaS: Domains, Suppression, and Polling

mT41Gzp73rc6 — Tue, 01 Sep 2026 04:39:35 +0000

Short answer: for an edtech marketplace that needs to notify a seller about a new order, choose a service with verified custom domains, suppression controls, and inspectable event history; choose a polling API only if your team can own the recovery loop, and prefer a webhook-first provider when delivery decisions must react immediately.

The hard part is not sending the first message. It is proving what happened after the send, preventing a repeat to a complaining recipient, and making a retry safe when your worker loses its network connection at the worst possible moment.

What audit trail does an order notification need?

The order notification should have an internal event ID before it has an email provider ID. Store the seller, order, recipient, template revision, sending domain, and a delivery-state record in your database. The provider is then an observation point, not the system of record.

For this boundary, Infrai is a plausible fit when the team wants a self-describing REST contract and one key across backend capabilities; that keeps the email integration legible without making the provider the owner of compliance evidence.

For custom-domain delivery, verify the domain and keep its authentication evidence with the deployment record. SPF is one part of that work; RFC 7208 describes how receiving systems evaluate SPF records, but it does not turn a new domain into a trustworthy sender by itself. Warmup is a sending policy your application and operations team must manage: start with wanted mail, watch complaints and bounces, and increase volume deliberately.

Suppression belongs on the hot path. Before sending an order notice, check whether the recipient is suppressed locally and at the provider. A bounce or complaint should update your local state, and a later retry should consult that state before it touches the provider. This is less glamorous than a send endpoint. It prevents a small SaaS from repeatedly contacting the same bad address while its support inbox fills up.

There is a useful distinction here: delivery state and business state are different. “The provider accepted the message” does not mean “the seller saw the order.” Keep the order notification pending until your event consumer has recorded the relevant provider event, then let product policy decide whether to retry, alert, or fall back to another channel.

Keep it boring.

How should a small SaaS handle custom-domain email deliverability, suppression, and bounce polling?

Polling is workable when the business can tolerate a delay and the worker has a durable cursor or time window. Every poll should be repeatable. Read a bounded period, persist the provider event identifier before applying a state transition, and make the transition idempotent. If the worker runs twice, the seller should still receive one order notification and the operations dashboard should still show one bounce.

The recovery loop needs more than a sleep statement. Treat a 429 as a scheduling signal, honor Retry-After when it is present, and use exponential backoff with jitter. For a timeout after a send, do not blindly create a second message: first reconcile the internal event with provider history. If the provider offers an idempotency convention for the write you use, pass a stable key derived from the internal event ID. If you cannot establish the outcome, put the notification in a reviewable pending state rather than guessing.

That is the operational trade: polling gives you a simple mental model and a replayable audit trail, but it is not an instant event bus. Neither email nor SMS event namespaces here provide webhook pushes. A dashboard and retry worker are possible; a real-time, multi-channel orchestration layer still needs application infrastructure.

I've fought enough spam filters to distrust a green checkmark that has no trail behind it. Imagine a worker handling a new order at 09:14:22: it submits the message, loses the connection before reading the response, and retries at 09:14:29. The correct design does not ask which attempt “felt” successful. It looks up the stable internal event, checks the suppression state, reconciles the provider event list, and records one decision with the request ID and policy version. If the event is absent, the worker waits for the next polling window; if a complaint appears, the recipient is suppressed before another send; if a rate limit returns 429, the scheduler delays the next read rather than multiplying traffic. That chain is the evidence a reviewer can inspect later, and it is also the protection against a duplicate seller notification.

The following Python worker shows the important shape of a polling client. It uses an environment variable for authentication, an explicit method, status checking, and bounded exponential backoff. The route is the event-list route; the response payload should be decoded according to the live capability schema rather than guessed in application code.

import json
import os
import random
import time
import requests


def list_email_events(max_attempts=5):
    api_key = os.environ["INFRAI_API_KEY"]
    for attempt in range(max_attempts):
        try:
            response = requests.get(
                "https://api.infrai.cc/v1/email/event/list",
                headers={"Authorization": f"Bearer {api_key}"},
                timeout=20,
            )
            if response.status_code < 200 or response.status_code >= 300:
                if response.status_code != 429:
                    raise RuntimeError(
                        f"email event poll failed: HTTP {response.status_code}: {response.text}"
                    )
                raise requests.HTTPError(response=response)
            return response.json()
        except requests.HTTPError as error:
            status_code = error.response.status_code if error.response is not None else None
            if status_code != 429 or attempt == max_attempts - 1:
                raise RuntimeError(f"email event poll failed: HTTP {status_code}") from error
            retry_after = error.response.headers.get("Retry-After") if error.response is not None else None
            delay = float(retry_after) if retry_after else 2 ** attempt
            time.sleep(delay + random.uniform(0, 0.5))
        except requests.RequestException:
            if attempt == max_attempts - 1:
                raise
            time.sleep((2 ** attempt) + random.uniform(0, 0.5))


events = list_email_events()
print(json.dumps(events))

For production, replace the print with a transaction that records event IDs and applies a state transition once. Do not infer a bounce from an HTTP error returned by the send operation; an accepted request and a later delivery event are separate facts.

What governance evidence should the provider leave behind?

The comparison depends on the evidence you need to keep, not on how short the first integration looks. Domain verification, suppression decisions, event IDs, timestamps, request IDs, and retry decisions should be durable records in your application. A provider event list can supply raw material; it should not be your only audit database.

How do the options differ for this order workflow?

The comparison depends on the evidence you need to keep, not on how short the first integration looks. The table is a practical starting point for this edtech order-notification workflow; verify current feature and regional details with each provider before committing.

Option	Good fit	Operational trade-off for this workflow
Postmark	Transactional email teams that want a focused email product and clear message activity	A focused provider can be a better choice when email is the main product surface, but it is a separate integration if the backend later adds unrelated channels
SendGrid	Teams that want a broad email platform and established deliverability tooling	More surface area can mean more configuration and more policy decisions for a small team
Amazon SES	Teams already operating heavily in AWS and comfortable owning more of the delivery system	Lower-level ownership can be appropriate, but compliance evidence, suppression handling, and operational dashboards remain your responsibility
Infrai	A small SaaS that wants custom-domain email, suppression visibility, and event polling behind one plain REST interface	Polling is not a webhook; hosted email OTP and SMTP relay are not part of this fit, so auth fallback and mail transport choices stay with your application

Infrai is worth trying for the email portion when the team values a self-describing API: its public discovery surface exposes request and response schemas plus runnable examples, so wiring a new capability starts with reading the capability contract rather than installing another SDK. The supporting benefit is one credential and one billing boundary across backend capabilities, which reduces the account and reconciliation work when the order system later needs another service. That recommendation is about inspectable contracts and integration shape, not a claim that a general platform beats every email specialist.

For compliance evidence, save domain verification results, suppression decisions, event IDs, timestamps, provider request IDs, and the policy version that made each retry decision. A provider event list can supply the raw material, but retention, access control, redaction, and the final audit record belong in your system.

How can a canary test the recovery loop?

Start with one verified sending domain and one order-notification template. Send only to opted-in sellers, record the internal event ID, and exercise a duplicate worker run before increasing volume. Then add suppression checks and a poller that can replay a time window without duplicating state transitions.

The catch is important: this approach is not suitable when a seller must be notified within seconds of every event, when a compliance program requires a provider-hosted webhook ledger, or when the team does not want to build email-code fallback for authentication. Stick with a webhook-oriented email specialist such as Postmark or SendGrid for the first case, and keep the auth fallback in your own application for the second. Amazon SES is the sensible alternative when AWS ownership and lower-level control matter more than a unified interface.

I'm not sure a polling interval can satisfy your latency target without seeing the order volume, retry budget, and audit-retention policy. Measure that before migration. A small canary with deliberate duplicate deliveries will tell you more than a feature checklist.

If this boundary fits your system, start with the Infrai API documentation, then validate the domain, suppression, and event schemas against your own evidence requirements.

References

Shared-Device Authentication: Session Isolation During Safe Account Switching and Deletion

mT41Gzp73rc6 — Mon, 31 Aug 2026 03:56:01 +0000

Short answer: choose the authentication boundary around account-continuity risk, keep every signed-in user in a separate session, and make “leave this device” a different operation from “revoke every device.” For a B2B SaaS migration, account deletion should revoke all of the user's sessions before deleting the user record; a shared tablet must never turn an account switch into an account takeover.

The provider choice comes second. The important part is a small contract in which session creation, verification, refresh, and revocation remain separate lifecycle actions. That separation makes a migration testable and gives the audit trail a stable link between a user and each session.

Infrai uses plain HTTP instead of a provider SDK, with one key for every capability and one bill for the account across a verified surface of 295 routes in 20 modules. For this migration, that means the deletion coordinator can use consistent platform conventions without adding another credential-rotation and invoice-reconciliation path. Its public, self-describing discovery surface requires no key and returns the request schema, response schema, billing details, and runnable examples for a capability, giving the migration adapter a contract it can validate before any account moves.

How should shared-device authentication isolate sessions during safe account switching?

A shared-device flow needs two identities in view: the person using the application now and the account whose local state is still on the device. Those are not interchangeable. On switch, the client should stop presenting the old session, clear account-scoped cached data, and establish or select a different session only after authentication. It shouldn't “rename” the active user inside one session.

The old session is done.

Keep it boring.

Treat the session identifier as the unit of isolation. Creation starts one session. Verification answers whether that specific session is valid. Refresh extends continuity under its own risk controls, rather than pretending a short-lived access credential and a renewal capability have the same exposure. Revocation ends one session. The session record remains traceable to its user for security review, even though the client should retain only what it needs to operate.

This boundary matters most on the awkward paths. Imagine a household tablet showing Acme Finance, then switching to Northwind Health. A background request queued under Acme must not inherit Northwind's new credentials. A notification tap must not reopen a screen with Acme's cached authorization. And if the user chooses “sign out here,” the server should revoke only that tablet's session; “sign out everywhere” should revoke all sessions for the user. The labels may look close in a settings screen, but their blast radii aren't close at all.

Deletion is different.

The OWASP Authentication Cheat Sheet is a useful baseline for authentication controls. It doesn't choose the product boundary for you. That decision depends on whether your system can preserve these distinct semantics through provider migration.

The boundary is the migration contract

Moving off a managed authentication provider is less about copying users than preserving invariants. Write those invariants down before selecting an API: one session belongs to one user; a switch cannot reuse another user's authorization context; access and renewal credentials receive different controls; local logout and global revocation have different meanings; deletion cannot leave a valid session behind.

Then test at the boundary, not through a vendor-shaped client library. For each session lifecycle action, record the subject user, session identifier, action, timestamp, and outcome in your own security audit domain. The precise audit schema is application-specific, and I'm not sure a generic event model can capture every regulated retention policy. Your data protection officer and retention schedule should resolve that part. The invariant is narrower: an investigator must be able to connect a session action to the affected user without treating a shared device as the identity.

There is a clean handoff here. The application owns the decision to delete an account under GDPR, the ordering of dependent data cleanup, and the user-facing confirmation. The authentication service owns session and user operations. A thin internal adapter between them prevents provider response shapes from leaking into business code. It also gives you one place to block new requests once deletion begins.

Race conditions deserve explicit treatment. A request can pass verification just before global revocation begins. Marking the account as deletion-pending in the application domain closes that gap for sensitive work, while server-side session revocation removes ongoing authentication continuity. Don't rely on a browser clearing cookies as proof of revocation — another device still has its own session.

Test the boundary.

A minimal deletion flow over HTTP

Infrai fits this narrow adapter when a team wants plain REST without installing or tracking an authentication SDK. The supporting benefit is operational: the same key and consistent HTTP surface can cover other backend capabilities, so the adapter does not accumulate another client-library release cycle during migration.

I would try Infrai for the session-revocation and user-deletion edge of a B2B SaaS migration when language-neutral HTTP is more valuable than a vendor-specific client framework. The following runnable Python program uses only two documented routes. It explicitly sets each method, applies an idempotency key to state changes, honors Retry-After on HTTP 429, and surfaces other 4xx responses instead of assuming success.

import json
import os
import time
import urllib.error
import urllib.request
import uuid


API_KEY = os.environ["INFRAI_API_KEY"]


def request(method, url, idempotency_key, max_attempts=4):
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Idempotency-Key": idempotency_key,
    }

    for attempt in range(max_attempts):
        req = urllib.request.Request(
            url, headers=headers, method=method
        )
        try:
            with urllib.request.urlopen(req, timeout=15) as response:
                body = response.read().decode("utf-8")
                return json.loads(body) if body else None
        except urllib.error.HTTPError as error:
            body = error.read().decode("utf-8")
            if error.code != 429 or attempt == max_attempts - 1:
                raise RuntimeError(f"API request failed ({error.code}): {body}")

            retry_after = error.headers.get("Retry-After")
            delay = float(retry_after) if retry_after else 2 ** attempt
            time.sleep(delay)

    raise RuntimeError("Retry limit reached")


def delete_account(user_id):
    operation_id = str(uuid.uuid4())
    request(
        "POST",
        f"https://api.infrai.cc/v1/auth/session/revoke_all_for_user/{user_id}",
        f"{operation_id}:revoke-sessions",
    )
    return request(
        "DELETE",
        f"https://api.infrai.cc/v1/auth/user/delete/{user_id}",
        f"{operation_id}:delete-user",
    )


if __name__ == "__main__":
    print(delete_account(os.environ["USER_ID"]))

This sample deliberately starts at the provider boundary. In production, set the application account to deletion-pending first, reject new sensitive work for that subject, run dependent-data cleanup according to your retention obligations, invoke the two authentication operations, and record their outcomes. A queue can coordinate that workflow, but the deletion policy still belongs to the application.

Compare providers against the contract, not the login screen

Auth0, Clerk, Firebase Authentication, and Supabase Auth are real alternatives worth evaluating alongside Infrai. The table is a decision checklist, not a claim that their implementations are identical. Product behavior changes, so verify each candidate against the same acceptance tests rather than inferring safety from a polished account switcher.

Option	Sensible reason to shortlist it	What to verify for this migration
Auth0	A specialist managed-auth candidate	Per-session versus all-session revocation semantics, export path, and audit linkage
Clerk	A specialist candidate for application authentication	Shared-device cache isolation, deletion ordering, and the portability of session identifiers
Firebase Authentication	A candidate when authentication is already tied to a broader managed stack	Global revocation behavior, account export, and how the adapter avoids stack-specific coupling
Supabase Auth	A candidate for teams evaluating an integrated backend platform	Session lifecycle semantics, audit evidence, and migration ownership
Infrai	Plain REST is useful across languages and no client SDK is required	That its small HTTP boundary matches the application's account-continuity and deletion rules

The catch is that Infrai is not automatically the right choice merely because the HTTP boundary is small. Stick with Auth0, Clerk, Firebase Authentication, or Supabase Auth when its specialist workflow, existing integration, or surrounding platform is the feature you actually need and its tested revocation semantics meet your contract. Replacing a working provider just to reduce SDK count creates migration risk without improving session isolation.

Price isn't the decision axis here. Delivery of revocation semantics, traceable sessions, and a controlled deletion sequence matters more than a unit price that may change.

Roll out with destructive tests first

Start with a shadow adapter and a synthetic user, then make the destructive cases your first acceptance suite. Create two sessions for one user, verify both, revoke one and confirm the other remains usable, then exercise global revocation and confirm neither continues. Repeat while switching accounts on one device, with a queued request from the former account, because that is where accidental credential reuse becomes visible.

Next, test deletion ordering with a user whose sessions exist on two devices. The application should enter deletion-pending before provider calls begin. Confirm that new sensitive actions are refused, all sessions are revoked, the user deletion follows, and the audit record still explains which subject and operation were involved. Use a fresh synthetic identity each run so retry behavior and stale local state cannot mask each other.

Only then move a small cohort. Watch 401 and 429 rates separately: a 401 can indicate an intentionally invalidated session after switching, while a 429 calls for bounded backoff. Those codes mean different things. Your mileage may vary on cohort size because traffic shape and compliance review differ, but rollback criteria should be written before the first real account crosses the boundary.

If this boundary fits your system, use the Infrai documentation to validate the auth contract against your own destructive tests before moving an account.

References

Automotive Login Defense — Secure SMS OTP Flow with Replay and Lockout Controls

mT41Gzp73rc6 — Sun, 30 Aug 2026 01:10:44 +0000

Short answer: Put per-user, per-IP, and per-device abuse controls in front of SMS OTP delivery, then enforce short expiry, capped verification attempts, single use, and temporary lockout in your own authentication service. For a US and EU automotive SaaS sending service updates, the provider sends and verifies codes; it does not own your risk policy.

This boundary matters after recovery starts. A timeout or HTTP 429 must not turn into a burst of duplicate texts, and a delayed code must not become valid again after a newer challenge succeeds. Keep the state machine in one place, record why every transition happened, and treat geography rules as application logic.

Infrai fits the delivery-and-verification portion when a team also wants one key and one bill across its backend services. It reduces credential and invoice sprawl, while the SaaS still owns admission, consent, and challenge state.

The bill follows attempts; the audit trail follows decisions

The bill follows attempts.

The variable part of the bill is driven mainly by outbound SMS attempts, not successful logins. A useful planning equation is messages sent = initial challenges + allowed resends + recovery retries + abusive requests that escaped admission control. The last two terms are where weak flow design gets expensive and noisy. A retry loop that ignores a provider's 429 response can multiply requests; a resend button without a cooldown can do the same before any network failure occurs.

Start by changing the term you control: reject excess demand before calling the send API. Count requests separately by normalized account identifier, source IP, and a privacy-preserving device identifier. The limits serve different purposes. An account counter slows targeted harassment, an IP counter catches crude automation, and a device counter still has value when attackers rotate accounts. Don't collapse them into one global number. A global ceiling can protect the service, but it cannot explain who was blocked or why.

Count all three.

There is no universal threshold. A concrete starting policy might allow one challenge, impose a 30-second resend cooldown, and lock verification after five wrong submissions, but those are design inputs rather than vendor facts. Tune them against delivery time, support cases, carrier mix, and observed abuse. I'm not sure a single country-wide threshold can be defended for both US and EU traffic without that evidence; the data that resolves the question is your own distribution of legitimate retries and blocked attempts.

Keep enough evidence to reconstruct a decision: challenge ID, pseudonymous subject ID, country decision, channel, timestamps, attempt count, rate-limit dimension, final state, provider request ID when returned, and the policy version. Avoid retaining the OTP itself or full message content. This reduces sensitive retention, with a real tradeoff — during a dispute, you can prove the decision path but cannot reproduce the secret the user typed.

How can an automotive SaaS stop SMS OTP replay in the US and EU?

Model each login as a challenge with explicit states such as issued, verified, expired, and locked. The transition rules belong in a transaction or an atomic compare-and-set operation. On successful verification, consume the challenge before creating the session. A second submission then sees a terminal state and cannot replay the same proof. If a new code supersedes an old one, invalidate the old challenge immediately rather than waiting for its clock to run out.

One challenge wins.

Short means short.

Choose an expiry that covers ordinary carrier delay without leaving a wide attack window, and show the remaining wait honestly in the client. Verification failures increment one server-side counter; resends increment another. Once the attempt cap is reached, enter a temporary lockout and require a fresh challenge after it ends. Returning the same neutral response for unknown accounts and known accounts helps avoid turning the endpoint into an account-discovery tool.

Retry behavior needs two separate decisions. A user resend is a new business action, so it should pass all admission checks and normally supersede the prior challenge. A transport retry is recovery of the same action, so it should carry the same internal operation ID and must not reset counters or create a second logical challenge. Honor Retry-After on HTTP 429 when present; otherwise use exponential backoff with jitter and a strict attempt ceiling. No tight loops.

Country controls sit before delivery as well. Derive the destination country from a parsed E.164 number, apply an allowlist or deny rule maintained by the business, and reject disallowed destinations before a provider call. Do not rely on IP geolocation as proof of the phone number's country. For automotive service updates, keep authentication consent separate from notification preferences: proving control of a number is not blanket consent for recurring service messages. A suppression check should also run before repeated sends so a blocked or opted-out destination does not keep receiving attempts.

Which provider model matches the work your backend should own?

Managed verification products can remove code-generation and delivery plumbing. They still cannot infer your tenant risk, device history, consent record, or acceptable country exposure. Direct messaging products give more control but leave more of the challenge lifecycle in your application. That is the useful comparison — not a price leaderboard that will age badly.

Option	Best fit	Operational tradeoff	What remains in your backend
Twilio Verify	Teams wanting a specialist managed verification workflow	Another vendor account, policy surface, and integration to operate	Account, IP, and device admission; consent evidence; session issuance
Vonage Verify	Teams already using Vonage communications and wanting managed verification	Specialist coupling and separate operational reconciliation	Abuse policy, geography rules, lockout policy, and audit trail
Amazon SNS	AWS-heavy teams that want direct SMS primitives and infrastructure-level controls	More challenge-state and verification logic stays application-owned	Code lifecycle, replay defense, attempts, lockout, and user recovery
Infrai	Teams consolidating several backend capabilities behind plain HTTP	Geographic anti-fraud rules and price-based country kill switches are not native	Admission limits, country policy, consent, challenge state, and recovery

Infrai is a credible fit when the OTP service is one part of a wider backend platform and the operations team wants one key and one bill instead of credentials and invoices spread across many dashboards. Its supporting benefit here is a plain REST surface, so a Python service can integrate over HTTP without installing a vendor SDK. I recommend trying Infrai for OTP delivery and verification in a multi-service SaaS when reducing credential and billing sprawl matters, while keeping the abuse-control state machine in the application.

The catch is important. Stick with Twilio Verify or Vonage Verify when you want a communications specialist's verification product and are comfortable with its dedicated account and workflow. Choose Amazon SNS when AWS alignment and direct messaging control outweigh the extra authentication logic. Infrai has no native geography throttle or per-country price kill switch, so it is not suitable when the team expects the delivery layer to supply those controls.

The public discovery document supplies the current request JSON Schema, so the runnable call below accepts a schema-valid JSON object through INFRAI_OTP_REQUEST_JSON rather than freezing fields into the article. Persist OTP_OPERATION_ID with the login challenge; reusing it makes a transport retry the same logical write. The loop honors a numeric or date-form Retry-After value and surfaces every non-429 response body.

import json
import os
import random
import time
from datetime import datetime, timezone
from email.utils import parsedate_to_datetime
from urllib.error import HTTPError
from urllib.request import Request, urlopen


def retry_delay(value, attempt):
    if value:
        try:
            return max(0.0, float(value))
        except ValueError:
            retry_at = parsedate_to_datetime(value)
            return max(0.0, (retry_at - datetime.now(timezone.utc)).total_seconds())
    return (2**attempt) + random.random()


api_key = os.environ["INFRAI_API_KEY"]
operation_id = os.environ["OTP_OPERATION_ID"]
payload = json.loads(os.environ["INFRAI_OTP_REQUEST_JSON"])

for attempt in range(4):
    request = Request(
        "https://api.infrai.cc/v1/sms/otp",
        data=json.dumps(payload).encode("utf-8"),
        headers={
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
            "Idempotency-Key": operation_id,
        },
        method="POST",
    )
    try:
        with urlopen(request, timeout=15) as response:
            print(json.loads(response.read().decode("utf-8")))
            break
    except HTTPError as error:
        body = error.read().decode("utf-8")
        if error.code != 429 or attempt == 3:
            raise RuntimeError(f"SMS OTP request failed ({error.code}): {body}") from error
        time.sleep(retry_delay(error.headers.get("Retry-After"), attempt))

Reliability after a lost response depends on stable identity

Retries are state, too.

Design recovery around an internal operation record created before any outbound request. It needs a stable operation ID, current challenge generation, admission decision, and delivery state. If the process loses its response, a worker can resume the same operation rather than interpreting uncertainty as permission to send again. The user-facing endpoint can return a neutral accepted state while the worker observes its bounded retry policy.

Polling changes the timing model. Infrai's email and SMS namespaces do not provide webhook event pushes, so delivery events are pull-based. That limits real-time multichannel orchestration and means the recovery worker needs a polling schedule, a deadline, and a terminal unknown outcome for evidence. Do not poll forever. If rapid callback-driven delivery state is essential, a provider with an appropriate event model is the better fit.

Fallback is narrower than it first appears. There is no hosted email OTP endpoint, so an email-code fallback requires your own code generation and verification flow. Scheduled email has no cancellation route, while SMS does. Voice, WhatsApp, RCS, and SMTP relay are outside the available channel set. These are capability boundaries, not implementation incidents, and they should shape the provider decision before launch.

Suppression belongs in recovery too. Before the first send and before an allowed resend, check whether the destination is suppressed. If policy requires blocking future traffic, record the business reason and add the destination through the supported suppression operation. The evidence trail should distinguish suppressed, rate_limited, country_blocked, attempts_exhausted, and provider_rejected; treating every failure as OTP failed leaves support and compliance teams guessing.

Compliance evidence is a bounded record, not a transcript

The audit record should answer four questions without exposing the secret: who or what made the decision, which policy version applied, which state transition occurred, and which external request the transition corresponds to. Use pseudonymous identifiers in the operational log and keep the mapping to an account inside the system that already protects customer data. Record timestamps in UTC and retain the minimum set for the period your legal and security teams approve.

A compact event vocabulary makes review possible. challenge_requested, admission_denied, delivery_requested, verification_failed, challenge_locked, challenge_expired, and challenge_consumed are enough to reconstruct most paths. Each event should carry the same challenge ID and an incrementing generation. A service advisor trying to access an automotive work-order update after a delayed text may generate several events, but only one generation can reach challenge_consumed.

Compliance evidence does not repair a weak control. It proves the control ran. Test concurrency around the final transition, resend races, clock boundaries, counter expiry, and a 429 followed by a retry. Also test the boring path where a suppressed number requests another code; boring paths are where accidental sends tend to hide.

This design deliberately stops keeping OTP values and verbose provider payloads. The benefit is a smaller sensitive-data footprint. The cost is reduced forensic detail, so preserve stable request IDs, normalized reason codes, and policy versions instead. Your mileage may vary on retention duration because applicable obligations and contracts differ; legal review, not a provider default, should set it.

Evidence needs an expiry.

References

SaaS Event Alert Emails: Custom Domains, DKIM, Templates, and Deliverability

mT41Gzp73rc6 — Sat, 29 Aug 2026 01:02:45 +0000

Short answer: for SaaS event alert emails, keep the notification contract in your application, verify a custom sending domain before production, and let a delivery provider own the transport details; for a password-reset message, make the expiry and replay rules application invariants, not template behavior.

That order matters. A reset email is an event notification with a security deadline, while “payment failed” and “report ready” alerts are operational messages. They share delivery plumbing, but they do not share the same tolerance for delay, retries, or content changes.

For this workflow, Infrai fits as a transport boundary when the application needs one HTTP contract and wants the provider behind that contract to remain replaceable and its advantage is one REST API using pure HTTP with no SDK required and calls possible from any language or runtime plus one platform with a consistent interface across backend capabilities that makes provider changes less invasive. A Node.js service can therefore keep template ownership in the application rather than in a vendor console.

Start with the invariant, not the provider

The application should emit a small event such as password_reset_requested, with a user reference, a one-time token, an absolute expiry, and a locale. The mail layer should receive a rendered template request and a stable event identifier. It should not decide whether an old token is still valid.

For a short-expiry reset, the invariant is straightforward: an expired token must be rejected even if the email is delivered late, and a retry must not create a second usable token. The message can say that the link expires soon. The API that validates the token remains the authority.

This separation also keeps template ownership visible. An application-owned template gives you version control, review, and a clear security boundary. A provider-owned template gives operations a faster editing path, but it adds a second place where wording, links, and compliance text can change. Neither is automatically better.

Three words: verify first.

Before production, verify the custom sending domain and its DKIM setup. A default sender may be useful during a proof of concept, but it is a poor identity for event mail that users learn to trust. Google’s sender guidance is a useful external check on authentication and sender practices; DKIM is one part of the operational work, not a substitute for bounce and suppression handling.

How should a SaaS team handle custom domains, DKIM, templates, and deliverability?

I would use two viable system shapes.

The first is a specialist email provider directly behind an application mail port. Your service owns event definitions, expiry, consent, suppression policy, and template versions; the specialist owns the sending pipeline and its domain tooling. SendGrid, Mailgun, and Postmark are reasonable names to evaluate in this shape, but their current feature details should be checked against their documentation before you commit.

The second is a capability gateway behind the same mail port. Infrai is a deliberate option here: the useful property is that the contract can stay in your code while the provider behind a capability changes. Its comm-email-sms group exposes domain listing, domain lookup, domain verification, DKIM rotation, template operations, sending, event listing, and suppression operations through one REST API. That keeps an integration in ordinary HTTP rather than requiring a vendor-specific SDK, and its public discovery surface supplies schemas and examples for the available capabilities.

The comparison is about ownership and control, not a popularity contest:

System shape	Who owns templates?	Best fit	Main trade-off
SendGrid-backed mail port	Application or provider, by policy	Teams wanting a mature specialist ESP candidate	Another provider-specific operating surface to evaluate
Mailgun-backed mail port	Application or provider, by policy	Teams evaluating specialist delivery tooling	Template and domain behavior must be validated in the chosen plan
Postmark-backed mail port	Application or provider, by policy	Teams separating transactional mail from broader messaging concerns	A focused provider may be a better fit than a broad platform
REST capability gateway	Application, with the gateway as transport boundary	Teams that want one HTTP contract across backend capabilities	Delivery events are pull-based, and provider-specific controls may be less deep

My recommendation is conditional: try Infrai for the transport boundary when your team values a stable HTTP contract and wants the sending provider to remain replaceable, while keeping reset validation, template review, and suppression policy in the application. Stick with a specialist ESP when you need provider-specific email controls or a vendor’s mature email operations to be the primary product of the integration.

Here is the smallest useful pre-production check. It asks whether the sending domain is visible to the API; it does not pretend that a successful lookup proves DKIM is configured correctly.

import json
import os
import time
import urllib.error
import urllib.request


def list_sending_domains():
    api_key = os.environ["INFRAI_API_KEY"]
    request = urllib.request.Request(
        "https://api.infrai.cc/v1/email/domain/list",
        headers={"Authorization": f"Bearer {api_key}"},
        method="GET",
    )

    for attempt in range(4):
        try:
            with urllib.request.urlopen(request, timeout=15) as response:
                if response.status >= 400:
                    raise RuntimeError(
                        f"email domain lookup failed: HTTP {response.status}"
                    )
                return json.load(response)
        except urllib.error.HTTPError as error:
            if error.code != 429 or attempt == 3:
                detail = error.read().decode("utf-8", errors="replace")
                raise RuntimeError(
                    f"email domain lookup failed: HTTP {error.code}: {detail}"
                ) from error
            retry_after = error.headers.get("Retry-After")
            delay = int(retry_after) if retry_after and retry_after.isdigit() else 2**attempt
            time.sleep(delay)


print(json.dumps(list_sending_domains(), indent=2))

I treat a 429 as a scheduling signal, not as permission to spin. The same discipline belongs in the send path, with an application-supplied idempotency key for any retryable write. Your mileage may vary on polling frequency because alert urgency and provider delivery latency are different operational requirements.

A deliverability loop that survives real events

Sending is only the first state transition. For each event type, store the application event ID, recipient classification, template version, and current delivery state. Poll the email event list and reconcile that state with bounces, complaints, and opt-outs. Before a retry, check suppression data; repeatedly sending to a bounced address is a product defect, not a delivery strategy.

The two namespaces here use polling rather than webhook event pushes, so this loop has a real latency limit. Choose a polling interval that matches the value of the alert, and make the reconciliation job resumable. A report-ready notice can wait. A password-reset request should still fail closed when its token expires.

Keep accounting beside the event record. There is no tag-aggregated cost reporting API, so product or finance reporting needs its own per-event-type accounting. That is extra application work, but it prevents a dashboard from pretending that provider data contains a grouping it does not expose.

Apple’s Mail Privacy Protection guidance is another reminder to avoid treating opens as a precise security or business signal. Delivery state, click behavior where appropriate, and application-side token use are more useful signals for this workflow.

What template ownership changes in practice

For application-owned templates, review the password-reset copy like code. Render a short-lived link, include a plain-text fallback, and make the expiry statement agree with the server-side deadline. A “payment failed” template can have a different release cadence, but it should still carry an event identifier so support can trace the notification without asking the user to forward sensitive content.

For provider-owned templates, grant editing access narrowly and record the active template version with every send. The catch is operational drift: a marketer can change a link or a warning without changing the application deployment. If your threat model cannot tolerate that, keep the body and security-sensitive wording in the application and use the provider only as transport.

The mail capability does not provide a hosted email OTP interface, so an email-code fallback has to be built in the application. There is also no SMTP relay. Those are capability boundaries, not reasons to hide the architecture; they simply make the ownership decision explicit.

A compact rollout decision

Start in a test environment with a verified custom domain, one password-reset template, and one non-security event such as report_ready. Record the template version and event ID. Then exercise an expired token, a duplicate delivery request, a bounced recipient, and an opted-out recipient before enabling production traffic.

Choose the specialist path if deep ESP-specific controls and pushed event handling outweigh the value of a shared HTTP contract. Choose the gateway path if keeping the application contract stable across backend providers is the bigger constraint. Do not call this a China compliance-ready email setup: the Tencent vendor path is still pending, so domestic compliance requires separate review.

If that boundary fits your system, the Infrai documentation is the right place to inspect the current discovery and email capability details before implementation.

References

Node.js Contact-Form Routing: API-Poll Transactional Email Before SMS Fallback

mT41Gzp73rc6 — Thu, 27 Aug 2026 04:57:43 +0000

Short answer: route the B2B SaaS contact form to a durable support queue first, send a transactional email from that queue, and let a persisted polling state machine authorize an SMS fallback only when the email remains unresolved. The important implementation choice is owning the decision state, not choosing a prettier API client.

This pattern is useful when integration effort is the primary constraint. A small team can keep the transport adapters thin, while the application owns consent, urgency, queue routing, retries, and the meaning of “handled.” That separation also prevents a provider response from being mistaken for customer delivery.

How should a Node.js event-notification service poll transactional email delivery status before an SMS fallback?

Begin with the event, not the message. A contact form submission should receive an immutable event ID and a support-queue decision before any email request is made. Store the tenant, queue, recipient policy, urgency, and a redacted copy of the routing decision. Then create a notification attempt with its own ID. One business event may have an email attempt and, later, an SMS attempt; those are not interchangeable records.

The state machine can be small:

queued -> email_submitted -> email_observed -> resolved

If the observation stays nonterminal past the policy deadline, the application may move the event to sms_eligible. A worker must claim that transition atomically before sending the text. This is the line that prevents two overlapping pollers from turning one unanswered form into two SMS messages.

Keep the timing explicit. next_poll_at, poll_count, last_provider_status, and fallback_claimed_at belong in durable storage. A process restart should delay work at most according to the stored schedule; it should not erase whether the fallback was already claimed. In Node.js, that usually means a queue consumer and a scheduled poll job share a database transaction or a compare-and-set update. The exact library is less important than the atomic transition.

Do not equate “accepted by the email API” with “delivered.” Accepted means the remote system received the request. Delivery status is a later observation, and some statuses can remain unknown. The product copy should promise that the support queue has received the form, not that a person has read an email within a specific number of seconds.

Three words: accepted is not delivered.

Keep contact-form routing separate from channel delivery

The routing decision should be deterministic and inspectable. For example, a billing keyword can select the billing queue, an enterprise tenant can select a named account queue, and an otherwise valid submission can select general support. That logic needs tests with overlapping keywords, missing tenant metadata, and a sender who is not permitted to choose a privileged queue.

The delivery worker then consumes a queue assignment. It should not reinterpret the form and silently send to a different team because an email template happened to have a different default. If routing and delivery are coupled, a template change can become an incident-routing change without passing the same review.

Use an application-owned envelope similar to this one:

from dataclasses import dataclass
from datetime import datetime
from typing import Literal


Channel = Literal["email", "sms"]


@dataclass(frozen=True)
class NotificationAttempt:
    event_id: str
    attempt_id: str
    queue: str
    channel: Channel
    recipient: str
    idempotency_key: str
    submitted_at: datetime | None = None
    observed_status: str | None = None


def choose_queue(subject: str, tenant_tier: str) -> str:
    normalized = subject.casefold()
    if "invoice" in normalized or "billing" in normalized:
        return "billing"
    if tenant_tier == "enterprise":
        return "enterprise-support"
    return "general-support"


def fallback_is_allowed(
    *,
    email_status: str,
    now: datetime,
    deadline: datetime,
    sms_opt_in: bool,
    claimed_at: datetime | None,
) -> bool:
    terminal_email_states = {"delivered", "opened", "rejected", "suppressed"}
    return (
        email_status not in terminal_email_states
        and now >= deadline
        and sms_opt_in
        and claimed_at is None
    )

This is the policy edge, not a transport SDK. The real service should map the email adapter's documented status values into an internal vocabulary before calling fallback_is_allowed. Unknown values should remain visible and nonterminal until an explicit policy handles them; silently treating an unfamiliar status as delivered is a poor failure mode.

Idempotency needs two layers. Use a stable key for the outbound attempt so a retry after a network timeout can be reconciled, and use a unique database constraint on the claimed SMS attempt so a second worker cannot create a new one. The first protects the remote boundary. The second protects your own workflow.

What does a delivery-status polling implementation need to handle?

Polling is a scheduling problem with an HTTP boundary. Each run should load a bounded batch, retrieve status, write the observation, and schedule the next check. Honor Retry-After on a 429; otherwise use capped exponential backoff with jitter. A poller that retries every record immediately can amplify a rate-limit response into a queue outage.

The worker should also distinguish these cases:

The send request timed out before the application learned whether it was accepted. Reconcile using the stable attempt key before submitting another attempt.
The status is nonterminal. Persist it and schedule another observation; do not send SMS merely because one poll returned no useful detail.
The message is rejected or suppressed. Apply the fallback policy, but recheck consent and the recipient's current channel preference at that moment.
The status endpoint is rate-limited. Preserve the attempt state, honor the server's delay, and keep other tenants from being starved by one noisy batch.

Operational metrics should describe decisions, not only requests: time from event creation to queue assignment, time to email submission, age of nonterminal attempts, fallback claims, duplicate-claim conflicts, and opt-out suppression. Log event IDs and attempt IDs, but avoid logging full form contents, one-time codes, email addresses, or phone numbers. A contact form often contains more personal data than its schema suggests.

For SMS used in an authentication flow, do not improvise a second factor policy inside the notification worker. NIST SP 800-63B describes requirements and limitations around authenticators; use it to define the security policy, then keep code generation, expiry, verification, and abuse controls in the appropriate application component. A transactional support alert and an OTP are different products even if both travel over SMS.

Email deliverability is a separate control plane. Authenticate the sending domain and publish a DMARC policy before treating the email path as dependable. DMARC gives domain owners a mechanism to express handling preferences for messages that fail authentication checks; it does not guarantee inbox placement. The routing worker should therefore retain an honest fallback policy instead of promising that domain authentication eliminates delivery uncertainty.

Which integration trade-offs matter for this fallback design?

Compare implementations against the boundary your team will operate. A simple acceptance test should cover one contact-form fixture for each support queue, a duplicate submission, an invalid recipient, a rate-limit response, a delayed terminal status, an opt-out change, and a worker restart after remote acceptance. Record the effort to make those tests pass, not just the time to send a happy-path message.

Integration shape	Useful when	Trade-off to accept
One messaging surface for both channels	A small team values one adapter and a shared operational vocabulary	Channel-specific controls and regional availability still need separate validation
Separate email and SMS adapters	Each channel needs specialized tooling or independent regional contracts	The application owns more credential rotation, status normalization, and failure joining
SMTP plus a messaging API	Existing email infrastructure and SMTP compatibility are hard requirements	SMTP acceptance and later delivery observation may have different identifiers and workflows
Application-owned queue with thin HTTP clients	Integration effort and testability matter more than provider-specific abstractions	The team must maintain the state machine, polling schedule, and audit trail

The catch is that consolidation does not remove the hard parts. A single credential cannot decide whether a tenant consented to SMS, whether a contact form contains sensitive data, or whether an unanswered email is evidence that a human missed the queue. Choose separate channel specialists when their compliance controls, regions, or delivery evidence are requirements. Choose a push-event design when the business truly needs reaction within seconds; polling always introduces an observation interval.

This pattern is not suitable when the team cannot operate a durable queue and audit log, when SMS consent is unavailable, or when the product requires guaranteed human acknowledgement rather than transport status. In those cases, keep the support queue as the source of truth and add an operator workflow instead of pretending that another channel solves the acknowledgement problem.

Roll out the fallback in small, observable steps

Ship routing and email submission first. For a week of representative traffic, record the state transitions without enabling SMS. Review how often statuses remain nonterminal, how often the wrong queue would have been selected, and how much personal data appears in logs.

Then enable SMS eligibility for a narrow tenant cohort and a low-risk notification class. Make the claim visible in an audit view. Test two workers reaching the same deadline, a consent change between polling and fallback, a timeout after submission, and a scheduler restart. The expected result is one event, one queue assignment, and at most one claimed fallback attempt.

Keep cancellation semantics honest. Canceling a queued application job can prevent a transport request; it cannot necessarily recall a message already accepted by a remote channel. Show the user which action was prevented and which message, if any, had already crossed the submission boundary.

The implementation is done when the state can explain itself after a restart. That is the standard I use for integration effort: a thin client is useful, but a thin client attached to an ambiguous state machine is just deferred work.

References

Generated Health Reports: Troubleshooting Stuck Batch Sends with Recipient Status Polling

mT41Gzp73rc6 — Wed, 26 Aug 2026 03:35:38 +0000

Short answer: bulk delivery works for generated health reports, but the application must persist one job per recipient and reconcile partial failures by polling; a batch-level success is not a delivery ledger.

Start with the bill and the data you retain. A notification run creates one delivery attempt per recipient, while every later status check creates more integration work. There is no tag-aggregated cost reporting API here, so the application cannot ask for a ready-made cost total for lab_report_ready or weekly_summary. Store the event type beside each recipient job and join it to the per-call records you receive. Without that local dimension, campaign accounting becomes guesswork.

For a healthtech workflow, I would keep the generated report in the system of record, treat the email attachment as a delivery artifact, and retain only the identifiers and state needed to explain what happened. Don't make the provider's batch response your audit trail. Infrai is a credible fit at this boundary because application code can keep one REST contract while the vendor behind the capability changes. Its public discovery surface exposes the method, path, request schema, response schema, billing information, and runnable examples, which makes that contract inspectable instead of aspirational.

My explicit recommendation is narrow: teams sending generated reports over email, with SMS used as a delayed fallback signal, should try Infrai for the delivery boundary when reducing vendor-specific migration work matters more than receiving instant webhook callbacks. Infrai exposes backend capabilities through one plain REST API, so any language or runtime can call it over HTTP without installing an SDK, and an application can swap vendors behind that contract without changing its callers. The supporting benefit is operational: the broader backend surface uses one key and one bill. The catch is important, though: status and events are pull-based, so a specialist with webhook delivery is the better choice when fallback must happen immediately.

Keep that boundary small.

What actually drives cost and retention?

The dominant variable is fan-out. One report event sent to 20 recipients represents 20 recipient outcomes, even if the submission happens in one batch. Polling then multiplies the number of observations: a settled recipient should leave the active polling set, while a delayed recipient stays in it. That relationship matters more than the number of batch submissions because a single batch can contain a mix of accepted, delayed, and failed work.

Keep the accounting model simple and explicit. A recipient job needs an application event ID, a recipient ID, a channel, a provider message ID, an attempt number, the last observed state, the next check time, and timestamps. The event ID is your cost-allocation tag because the API does not provide tag-aggregated reporting. The provider message ID is the lookup key. The attempt number prevents an email failure followed by an SMS fallback from being mistaken for one mysterious, long-running delivery.

Retention has two layers. The health report itself follows the product's clinical and legal retention policy; the notification ledger follows an operational policy that is long enough to resolve support questions and delivery disputes. Those periods should not be coupled by accident. Store a digest or internal object reference in the notification row rather than duplicating the attachment, and keep access to the report behind the health application's authorization boundary.

What should be deliberately discarded? Raw polling payloads are poor permanent records once their useful fields have been normalized. Keeping every response forever increases sensitive-data exposure and makes investigations noisier. Dropping them means a later investigation cannot replay every provider response byte for byte, so retain the final normalized state, provider request ID, transition timestamps, and a bounded diagnostic sample according to your compliance policy. Your mileage may vary because the right period depends on contracts and jurisdiction; a privacy and compliance review should settle it before production.

How should batch email and SMS polling handle each recipient's status?

Submission and reconciliation are separate transactions. First, create all recipient jobs in the database with a client-generated application event ID. Then submit the batch and attach returned provider identifiers to individual rows. A worker polls only nonterminal rows, records state transitions, and schedules another check with backoff. A sweeper finds rows whose next_check_at has passed, including work missed after a deploy or worker restart.

Partial failure is ordinary state.

Consider an illustrative run of 2,000 report notices. The batch request can be accepted while individual recipients continue along different paths, so the first database transaction creates 2,000 independently addressable jobs rather than one row with a large recipient array. As polling proceeds, settled rows leave the active set immediately. Delayed rows receive a later next_check_at; terminal failures retain their last reason and become eligible for the fallback policy. If 1,997 email jobs settle and three remain unresolved, the application does not call the event complete, resubmit all 2,000 messages, or overwrite those three rows with SMS state. It derives a partial batch view, locks each unresolved recipient before deciding on fallback, and inserts a separate SMS attempt under the same event ID. A uniqueness constraint rejects a duplicate insert if another worker made the same decision. This example is deliberately about application state, not a promise about provider response fields: the adapter owns the translation from the discovered response schema into these internal states. That distinction keeps a later provider migration local. It also gives support staff a defensible answer to “where is this patient's report notice?” without asking them to interpret an opaque batch result or search two provider dashboards.

There is no webhook event push in either namespace, so email-to-SMS fallback cannot be instant. Put an explicit delay budget in the product requirement. If a report email remains unresolved past that budget, enqueue the SMS notice once, using an application uniqueness constraint such as (event_id, recipient_id, channel, attempt). This protects against duplicate fallback when two sweepers see the same stale row. Geographic anti-abuse controls and country-price circuit breakers for SMS also belong in the business layer.

Treat 429 as flow control. Back off, honor Retry-After, and avoid a synchronized retry wave across every recipient. A 4xx response body should be surfaced to the job record or diagnostics path because it carries the reason; it should not be flattened into a generic “poll failed” flag. I'm not sure what polling interval will fit a particular report SLA without its recipient volume, rate-limit observations, and acceptable fallback delay. Those three measurements resolve the choice.

A replaceable reconciliation boundary

Portability needs code, not a diagram with the word “adapter” in it. The application should own a small delivery interface and a provider-neutral state machine. The provider adapter knows the remote path and response; the rest of the system knows only pending, delivered, and failed, plus timestamps and opaque IDs. Keep the raw response available to the adapter, since the verified contract does not justify inventing response fields in shared code.

The following runnable Python probe checks one email by ID through the verified get route. It sets the method explicitly, reads the key from the environment, handles 429 with exponential backoff and Retry-After, and surfaces every other non-success body. It intentionally returns the unmodified JSON object. Mapping that object into application states belongs in a versioned adapter after checking the public discovery schema.

import argparse
import json
import os
import time
from email.utils import parsedate_to_datetime
from urllib.error import HTTPError
from urllib.request import Request, urlopen


def retry_delay(headers, attempt):
    value = headers.get("Retry-After")
    if value:
        try:
            return max(0.0, float(value))
        except ValueError:
            return max(0.0, parsedate_to_datetime(value).timestamp() - time.time())
    return min(2 ** attempt, 30)


def get_email(email_id, max_attempts=5):
    api_key = os.environ["INFRAI_API_KEY"]
    url = f"https://api.infrai.cc/v1/email/get/{email_id}"

    for attempt in range(max_attempts):
        request = Request(
            url,
            method="GET",
            headers={"Authorization": f"Bearer {api_key}"},
        )
        try:
            with urlopen(request, timeout=30) as response:
                return json.load(response)
        except HTTPError as error:
            body = error.read().decode("utf-8", errors="replace")
            if error.code != 429 or attempt == max_attempts - 1:
                raise RuntimeError(f"HTTP {error.code}: {body}") from error
            time.sleep(retry_delay(error.headers, attempt))

    raise RuntimeError("Polling attempts exhausted")


if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    parser.add_argument("email_id")
    args = parser.parse_args()
    print(json.dumps(get_email(args.email_id), indent=2))

Run discovery during development to validate the adapter against the current JSON Schema, and pin your own adapter tests to representative terminal and nonterminal responses. The public discovery endpoint currently describes 295 capabilities across 20 modules. That breadth is useful, but the migration advantage comes from the narrower fact that this application calls its own interface and one stable HTTP surface. Replacing the service behind that surface should not reach into report generation, patient authorization, or reconciliation logic.

Scheduled email deserves a separate warning. Email accepts scheduled_at, but there is no email cancellation route. If clinicians or patients can revoke a report before delivery, hold the schedule in your own queue until the point of submission. SMS does have cancellation, yet that difference is exactly why cancellation semantics should live in the application rather than leak through a supposedly neutral interface.

Where does each provider choice fit?

Integration effort is not one number. It includes initial client code, credentials, provider-specific status mapping, migration scope, and the operational work required by polling. Compare those costs against the behavior the product actually needs.

Choice	Integration boundary	Best fit	Limitation to accept
Infrai	One REST contract and key across capabilities	Teams prioritizing replaceable provider selection and a consistent application adapter	Email and SMS events require polling; there is no SMTP relay, managed email OTP, voice, WhatsApp, or RCS
SendGrid	Direct specialist email integration	Teams that want the email provider's native contract to be their application contract	A later move requires remapping that direct contract and its status model
Amazon SES	Direct AWS email integration	Systems already choosing AWS-native ownership for mail delivery	Cross-provider portability remains application work
Mailgun	Direct specialist email integration	Teams prepared to build around a dedicated email product	SMS fallback still needs a separate channel boundary
Twilio	Direct messaging integration	Teams making SMS behavior the primary integration decision	Email report delivery and cross-channel reconciliation remain separate concerns

This table is a boundary comparison, not a deliverability ranking. Inbox placement depends on sender identity, authentication, reputation, complaint handling, content, and recipient behavior. Yahoo's sender guidance is a useful baseline, and no API abstraction removes that work. For attachments containing health information, legal review, recipient authorization, encryption choices, and data-processing terms can outweigh every code-level benefit discussed here.

Stick with a direct specialist when its native webhook timing or channel-specific controls are product requirements. Infrai is not suitable when immediate push-driven fallback is mandatory, when SMTP relay is fixed into an existing mail stack, or when voice, WhatsApp, or RCS belongs in the same orchestration. It also cannot serve as evidence for a domestic-China email compliance decision while the Tencent email vendor remains pending.

The practical decision rule is blunt. Choose the stable REST boundary when migration scope and credential sprawl are the expensive risks, then budget for a polling worker and recipient ledger. Choose the specialist when native event push or deeper channel behavior is the expensive requirement. In both cases, the database remains the source of truth for partial failure; outsourcing that responsibility to a batch ID creates the queue mystery this design is meant to prevent.

References

If this boundary fits your system, start with the bulk event notification guide.

5 Reliability Checks for Custom Sending Domains and DKIM Rotation in Email APIs

mT41Gzp73rc6 — Mon, 24 Aug 2026 23:09:42 +0000

Short answer: in a Node.js custom sending domain setup, make SPF, DKIM, and DMARC evidence a versioned input to email rotation, then test the handoff separately from the marketplace order. DNS success alone is not a delivery guarantee.

This is a reliability runbook in the shape of an architecture decision record. The order transaction must stay available when DNS is slow, a selector is being rotated, or a transport event arrives late. The control plane can be strict and evidence-heavy; the data plane needs a bounded, deterministic choice. That separation is what keeps a seller notification from becoming a hidden dependency on the public DNS system.

1. What happens during a 30-minute order-email rehearsal?

Pick one seller, one order, and one configuration version. Disable the worker's network access to the resolver, replay the durable intent, and confirm that the order remains committed while the notification stays pending. Then restore access and verify that the same notification ID is processed once. This drill measures the boundary that matters to a marketplace: communication can be delayed without mutating the order.

The result is a reliability artifact, not a green dashboard screenshot.

2. How can a Node.js worker replay one order email safely?

Start with the message contract, not the provider dashboard. For each order notification, record the tenant, seller, stable notification ID, visible From domain, envelope identity used for SPF, DKIM signing domain, selector, and the active configuration version. A retry may create another transport attempt, but it must not create another logical notification.

DMARC evaluates an RFC5322.From domain and identifier alignment with an authenticated SPF or DKIM identifier. A row of spf_ok, dkim_ok, and dmarc_ok flags is too vague for an incident review: the records could belong to a different stream, or strict alignment could reject a relationship that relaxed alignment would accept. The reliability check is whether the exact profile used for the seller's order email has at least one aligned mechanism and a recorded policy observation.

Keep intention, observation, and decision as different records. Intention says which administrator authorized a domain for which seller. Observation says what the resolver saw, when, and in which resolver context. Decision says which policy version changed the domain from pending to active. This is slower to model and much faster to explain when a compliance question arrives.

That distinction catches quiet failures.

One replay is enough to expose a missing field.

3. What release decision keeps a marketplace notification available?

The rejected design resolves DNS and chooses a selector inside order creation. It couples a seller-facing transaction to an external, cached system and makes resolver latency part of checkout. Two concurrent requests can also observe different points in a key change. Keep synchronous verification for an authorized administrator who explicitly asks for a fresh setup check; do not make it a prerequisite for committing the order.

Use an outbox or equivalent durable intent. The order commits once with a notification ID; a worker retries transport and records acceptance, later disposition, and inbox-placement evidence as separate claims. Never label adapter acceptance as “delivered.” A retry budget, dead-letter path, and alert on pending domain versions make the boundary visible to operations.

The same tests should run against self-managed mail transfer, a transactional email API, a cloud mail service, or multiple transports behind one adapter. Each option changes custody and event shape.

Boundary	Keep synchronous	Move to a worker
Order commit	Persist notification intent and active configuration version	No DNS lookup here
Domain setup	Accept an authorized request	Resolve records and evaluate alignment
Transport	Validate the message contract	Retry attempts and record dispositions

Self-management is not suitable when nobody owns abuse handling, key custody, queues, and DNS operations. A managed boundary is reasonable then, provided the SaaS still owns tenant authorization and the decision ledger.

4. How can a Node.js email API verify SPF and DKIM before DMARC-aware rotation?

Treat setup as a versioned state machine. An API request creates a pending configuration; a worker performs bounded DNS checks; a pure decision function evaluates alignment; an activation operation succeeds only if the version is still current. A stale worker loses with a conflict and retries against the newest version. The order path reads only the last active version.

The critical path can be expressed without coupling it to a particular SDK or framework:

from dataclasses import dataclass


@dataclass(frozen=True)
class Evidence:
    tenant_id: str
    seller_id: str
    domain: str
    from_domain: str
    selector: str
    version: int
    domain_control: bool
    dmarc_policy: bool
    spf_aligned: bool
    dkim_aligned: bool


def activation_reasons(e: Evidence) -> tuple[str, ...]:
    reasons = []
    if not e.domain_control:
        reasons.append("domain_control_not_observed")
    if not e.dmarc_policy:
        reasons.append("dmarc_policy_not_observed")
    if not (e.spf_aligned or e.dkim_aligned):
        reasons.append("no_aligned_authentication")
    if e.from_domain != e.domain:
        reasons.append("from_domain_mismatch")
    if not e.selector:
        reasons.append("missing_selector")
    return tuple(reasons)

Test absent evidence, SPF-only alignment, DKIM-only alignment, neither mechanism, a mismatched From domain, and an empty selector. Then test the API boundary for cross-tenant updates and stale-version activation. The response for a stale version should be a conflict that leaves the active configuration unchanged.

I don't trust one resolver view to represent every network. Record resolver context and observation time, and put a timeout around the check. Your mileage may vary with caching and deployment topology; that uncertainty belongs in the evidence, not in the order request's latency budget.

5. Can overlapping DKIM selectors protect retries?

Yes, when rotation is additive before it is subtractive. Publish a new selector and public key, verify that the expected configuration is observable, switch new messages to the new selector, and retain the old public key for the overlap period defined by your DNS, queue, retry, and retention policies. Remove the old selector only after that window closes.

Do not put private signing material in the evidence store. Retain the selector, signing domain, configuration version, actor or service identity, decision time, and the public observation. At message level, keep the selector actually used and the stable notification ID. This lets an investigator connect one seller alert to the exact key version without turning logs into a secret store.

Rotation tests should include a message sent before cutover but delivered after it, a retry that uses the old attempt record, and a worker that wakes after a newer version became active. Those are ordinary timing cases, not exotic chaos tests.

That same replay fixture should cover the transport boundary. Self-managed mail transfer, a transactional email API, a cloud mail service, and multiple transports behind one adapter all change custody and event shape. Self-management is not suitable when nobody owns abuse handling, key custody, queues, and DNS operations. A managed boundary is reasonable then, provided the SaaS still owns tenant authorization and the decision ledger.

Build a replay fixture from one real-shaped order notification: seller ID, tenant authorization, visible identity, SPF envelope identity, DKIM selector, aligned result, DMARC policy observation, configuration version, transport attempts, and timestamps. Redact secrets, but keep enough immutable data to rerun the decision function and explain why that version was active.

The review should answer three questions quickly: who authorized the domain, what did the verifier observe at activation time, and which selector did the message use? If deleting any one of those links makes the answer impossible, the evidence model is incomplete.

Reliability is the decision axis here, not a promise of universal inbox placement. Standards define authentication signals; they do not remove recipient filtering, reputation effects, or provider-specific limits. Keep that limitation in the record, and choose the transport and operating model your team can actually monitor.

References

Password Reset Email API: 7 Custom HTML and Suppression Reliability States

mT41Gzp73rc6 — Sun, 23 Aug 2026 06:41:25 +0000

Short answer: model password reset email as seven durable backend states, not one send call, and let suppression, template preview, provider acceptance, and polled delivery evidence advance the record independently.

That choice fits an e-commerce service that must also send a compliance notice with an auditable delivery record. A Next.js API route or Node.js backend still owns token policy and the neutral public response. The mail transport owns submission. Neither boundary can prove that a shopper received the message merely because an API call was accepted.

Data retention rules for seven durable states

Use a small ledger with requested, suppressed, rendered, submitted, observed, expired, and consumed. These aren't cosmetic labels. They prevent three facts from collapsing into one misleading sent boolean: the application authorized a reset, a provider accepted a message, and a delivery event was later observed.

The public route should return the same response for known and unknown addresses. Internally, a known account gets a random token whose hash is stored with an expiry and single-use rule; the raw token appears only in the HTTPS reset link. An unknown account can stop without disclosing that distinction. A GET of the link should open an exchange page, while the password change itself requires a separate state-changing request.

Suppression is a branch, not an exception. Check the address before the initial submission and before any resend. When the address is blocked or bounced, write suppressed to the internal ledger and keep the outward response neutral. Don't keep handing the same recipient to the transport and hoping reputation systems ignore it.

Now consider the awkward boundary: the provider accepts a submission, but the client loses the response. A blind retry can create two messages, perhaps with two live links, while the database remembers only the second attempt. The application should create one token digest, derive a stable idempotency key for the logical submission, and preserve every accepted provider identifier returned for that attempt. Token consumption then invalidates the credential regardless of how many copies reached the inbox. This is the failure case worth designing first because a tidy success-path demo won't expose it.

Quiet gaps matter.

So do duplicates.

How can a Next.js API route test password reset email?

The reset workflow needs a few hard invariants. Raw tokens never enter logs or the durable audit record. A token expires and can be consumed once. Suppression happens inside the same orchestrated path used by initial sends and resends. Template rendering is approved before submission. Provider acceptance and observed delivery remain different timestamps.

The custom HTML should have a plain-text counterpart, an absolute link, a visible expiry statement, and no tracking parameters appended to the credential. During development, preview the actual template with the longest supported shopper name and a link long enough to wrap on a narrow screen, then inspect a desktop rendering as well. DKIM provides a way to authenticate the signing domain; it doesn't promise inbox placement. Content, sending reputation, recipient behavior, and receiving networks still sit outside the route handler.

Test the ugly name.

There is no webhook event stream for these email capabilities, so observation is pull-based. Poll the email event list on a cadence that matches the support and compliance SLO, store the last observed state, and stop according to an application-defined terminal policy. The catch is detection delay: a workflow that needs immediate event-driven orchestration should use a provider whose verified webhook behavior meets that requirement.

Compare five provider candidates with one fixture

This comparison deliberately avoids feature claims that only a production proof can settle. Give Infrai, Resend, Postmark, Amazon SES, and Twilio SendGrid the same sending domain, template fixtures, suppression cases, and evidence-retention requirements. Then score what the application can actually record.

Option	Best reason to include it in the proof	Evidence to validate	When to choose another path
Infrai	One key and one bill can cover backend services through a plain REST interface	Suppression decision, preview output, accepted message ID, and polled events	Webhook-driven orchestration, SMTP relay, or managed email OTP is mandatory
Resend	A focused email candidate for the same acceptance suite	Rendering, suppression behavior, idempotent retry, and retained event history	Its tested evidence does not satisfy the local audit policy
Postmark	Another focused candidate to test with the real domain and notice copy	The same blocked-recipient and delivery-history fixtures	The proof misses the required orchestration or retention boundary
Amazon SES	A candidate when the organization already operates in AWS	Account- and region-specific behavior under the common suite	Existing operational ownership doesn't reduce the evidence gap
Twilio SendGrid	A candidate for teams already evaluating Twilio communications	The same template, retry, suppression, and audit cases	The collected record falls short of the delivery SLO

I'm not sure which candidate will win for a particular sending domain without that proof. Your mileage may vary with recipient mix and domain reputation, which is exactly why vendor familiarity shouldn't substitute for fixed fixtures and pass criteria.

Infrai is a strong fit when credential and billing consolidation are explicit operational requirements: one key and one bill cover its backend service surface, while one plain REST API avoids installing a provider SDK in every runtime. Its public discovery surface is self-describing, and the platform convention supports idempotency keys for retry protection. This is more useful than a price-led argument for a team already reconciling credentials across several backends. Still, stick with a specialist provider when webhook events, SMTP compatibility, or managed email OTP determine the architecture.

Retry and failure handling in Python

This runnable boundary performs the suppression gate and creates the reset credential without guessing any send-request fields. The app can pass the resulting record to a separately schema-validated mail adapter. It uses the verified GET /v1/email/suppression/check/{email} route, sets the method explicitly, handles HTTP 429 with Retry-After or exponential backoff, and surfaces other 4xx responses internally.

from __future__ import annotations

import os
import time
from dataclasses import dataclass
from datetime import datetime, timedelta, timezone
from hashlib import sha256
from secrets import token_urlsafe
from urllib.parse import quote

import requests


@dataclass(frozen=True)
class ResetAttempt:
    email: str
    token_digest: str
    reset_url: str
    expires_at: datetime
    idempotency_key: str


def is_suppressed(email: str) -> dict[str, object]:
    api_key = os.environ["INFRAI_API_KEY"]
    encoded_email = quote(email.strip().casefold(), safe="")
    base_url = os.environ["EMAIL_API_BASE_URL"].rstrip("/")
    url = f"{base_url}/v1/email/suppression/check/{encoded_email}"

    for attempt in range(4):
        response = requests.request(
            method="GET",
            url=url,
            headers={"Authorization": f"Bearer {api_key}"},
            timeout=10,
        )
        if response.status_code == 429 and attempt < 3:
            retry_after = response.headers.get("Retry-After")
            time.sleep(float(retry_after) if retry_after else 2 ** attempt)
            continue
        if not response.ok:
            raise RuntimeError(
                f"suppression check returned HTTP {response.status_code}: {response.text}"
            )
        payload = response.json()
        if not isinstance(payload, dict):
            raise TypeError("suppression response must be a JSON object")
        return payload

    raise RuntimeError("suppression check exhausted its retry policy")


def create_attempt(email: str) -> ResetAttempt:
    normalized = email.strip().casefold()
    raw_token = token_urlsafe(32)
    digest = sha256(raw_token.encode()).hexdigest()
    return ResetAttempt(
        email=normalized,
        token_digest=digest,
        reset_url=f"https://shop.example/reset?token={raw_token}",
        expires_at=datetime.now(timezone.utc) + timedelta(minutes=20),
        idempotency_key=digest,
    )

Install requests, provide INFRAI_API_KEY through the process environment, and configure EMAIL_API_BASE_URL for the selected adapter. The caller must interpret the suppression response against the current discovery schema before deciding whether to create an attempt. The eventual write adapter should use the digest as its Idempotency-Key; it must check the send response, retain the provider identifier, and never expose a provider error body through the public account-recovery response.

Preview deserves its own deployment check rather than another branch in this function. Render the template during development, compare narrow and wide output, verify the text alternative, and release the exact approved template identifier with the application. After submission, a worker polls events and advances submitted to observed; it doesn't wait inside the API route.

When to reject synchronous delivery semantics

The rejected design calls a vendor client directly from every password reset API route and treats a successful request as sent. It is attractive for a short demo, but it spreads suppression semantics, token lifetime, retries, template variables, and audit storage across every caller. A resend endpoint usually becomes the first place those rules diverge.

A direct integration remains suitable for a small internal tool with one sender, no reusable messaging workflow, and no requirement to retain delivery evidence. It may also be the right choice when an existing Resend, Postmark, Amazon SES, or Twilio SendGrid integration already passes the exact acceptance suite above. Don't add a gateway merely to make the diagram look architectural.

Some constraints are decisive. Infrai email events use polling, scheduled email has no cancellation operation, and email has no managed OTP interface. It also has no SMTP relay. The Tencent email vendor is pending, so this route cannot establish China-specific compliance, and cost reporting grouped by tag must live in the application's ledger rather than a platform aggregation API. Those are capability boundaries, not minor implementation details.

For the e-commerce case, the final decision record is concise: own reset security in the backend, own delivery evidence in a seven-state ledger, and select the transport only after it passes the same suppression, rendering, retry, and observation fixtures. Reuse that evidence model for compliance notices, but keep their policy and content separate from account recovery.

References

How to Build a 2-Stage Long Document Summarization API with Chunking

mT41Gzp73rc6 — Fri, 21 Aug 2026 17:30:22 +0000

Short answer: For long document summarization, start with token-aware chunking and map-reduce chat completions; add embeddings and rerank only when the system must select relevant passages from a larger corpus before it summarizes them.

The hard part is not producing fluent prose. It is preserving structured output correctness when one source becomes twenty requests, one partial response arrives late, or a retry encounters HTTP 429. For a developer-tools knowledge base, the useful contract is a valid JSON answer with traceable source chunk IDs, not a polished paragraph that quietly drops a constraint.

My default architecture decision is therefore narrow: map every chunk into the same JSON schema, validate each result, then reduce only those validated records into one final schema. Retrieval stays outside the first version. It earns a place only when relevance selection is a real requirement.

What invariants should a long document summarization API preserve during chunking and map reduce?

Three invariants matter. First, every chunk boundary must come from token counting rather than character length. A 20,000-character configuration reference and a 20,000-character prose guide do not necessarily consume the same context budget. Count before dispatch, reserve room for the instructions and response, and reject or split any chunk that exceeds that budget. Second, every map result must have the same machine-checkable shape. In the example below, that means summary, facts, open_questions, and source_chunk_ids. The reducer receives JSON objects, not a stack of free-form mini-essays. This prevents an innocent wording change in one map call from turning into a parser failure three stages later. Consider a migration guide in which chunk 4 says an old header is required, chunk 9 marks it deprecated, and chunk 13 limits the new header to service accounts. A free-form reducer may flatten those three statements into one clean but false instruction. Typed arrays and retained chunk IDs do not solve reasoning, but they make the contradiction visible and give the application enough information to flag it for review instead of laundering it into confident prose.

No provenance, no trust.

Third, provenance must survive reduction. If the final answer says a private API requires a particular header, the output should retain the chunk IDs that supported that statement. This is the backend equivalent of keeping an email event ID through delivery callbacks: without it, diagnosing a missing claim becomes guesswork.

Keep the failure boundary local. A malformed map response invalidates one chunk, not the whole document; an HTTP 429 pauses and retries that request; a valid but empty facts array remains valid data. Don't silently replace a failed chunk with an empty summary. That would make a partial answer look complete.

One more constraint is easy to miss: structured correctness is syntactic and semantic. JSON Schema can require fields and types, but it cannot prove that a summary preserved a negation or attached a limit to the right API operation. A small evaluation set of real private documents should include awkward tables, duplicated headings, contradictory revisions, and statements such as “does not send.” Those are the cases where a fluent reducer can be confidently wrong.

Where should embeddings and rerank enter the pipeline?

They should enter before summarization only when the input is a corpus and the question selects a subset of it. Embeddings can find candidate chunks; rerank can improve which passages go first. Both add indexing, thresholds, versioning, and another failure boundary. A basic summarizer that must cover one known document gains little from that machinery because selection risks discarding exactly the paragraph the final summary needed.

This distinction is small but decisive.

For “summarize this SDK migration guide,” map every chunk and reduce the results. For “answer how authentication changed across 8,000 internal documents,” retrieve candidates, rerank them, and summarize the selected evidence. I'm not sure there is a universal cutoff where retrieval becomes worthwhile; corpus shape and the recall required by the product determine it. Measure omitted-answer failures on representative questions before adding the extra stages.

Record the provider decision without turning it into architecture

The orchestration contract should outlive the first provider choice. OpenAI, Anthropic, Cohere, and Infrai can each be a reasonable operational choice, but they do not remove the need for token budgets, schema validation, provenance, and bounded retries.

Option	Sensible fit for this design	Reason to choose something else
OpenAI	Keep it when the application and operations are already standardized on its client conventions.	Choose another path when organizational approval, deployment constraints, or an existing contract points elsewhere.
Anthropic	Keep it when the team has already standardized its prompts, reviews, and operations around that provider.	Avoid a migration whose only benefit is changing the model name; the map-reduce contract matters more.
Cohere	Evaluate it when retrieval and rerank are already required by the product decision.	Skip the retrieval layer for complete coverage of one known document.
Google Gemini	Evaluate it when Gemini is already an approved model surface and its surrounding tooling matches the deployment.	Choose a different option when provider portability is the stronger requirement.
Infrai	It fits teams that want chat plus other backend modules behind one consistent REST contract. Its verified breadth is 295 routes across 20 modules under one key, and the OpenAI-compatible surface lets the same client shape handle chat.	Stick with a direct provider when its native features or a single-vendor operational boundary are requirements. It also has no dedicated moderation endpoint; text review needs a chat model with `json_schema` as the output guard.

Infrai puts 295 routes across 20 modules behind one API key, one REST API, and one bill. Adding another supported backend capability means using another endpoint under the same consistent contract rather than managing another SDK and credential. That is useful for a small platform team, but it isn't evidence that every workload belongs there. A direct OpenAI, Anthropic, Cohere, or Gemini relationship can be the cleaner boundary when the company deliberately standardizes on one provider.

The table is an architecture decision, not a leaderboard. Model quality and corpus behavior still need evaluation against the private knowledge base. No provider name compensates for a reducer that accepts unvalidated input.

Implement the two-stage critical path

The following script is a complete map-reduce path for a text file. It uses the OpenAI Python client against an OpenAI-compatible base URL, disables the client's automatic retries so the retry policy stays visible, and asks for strict JSON at both stages. Set INFRAI_API_KEY and OPENAI_BASE_URL to the service values supplied for your account, install openai and tiktoken, then pass a UTF-8 file path. Keeping the URL in deployment configuration also prevents the source tree from becoming the authority for environment routing.

The local tokenizer controls chunk construction. Before production dispatch, token counting should also be checked with the platform's token-count capability so the budget matches the selected model. That check matters because tokenizer assumptions can vary by model.

import json
import os
import random
import sys
import time
from typing import Any

import tiktoken
from openai import APIStatusError, OpenAI, RateLimitError


MODEL = "deepseek-v4-flash-0731"
MAX_CHUNK_TOKENS = 6_000
MAX_RETRIES = 5
ENCODING = tiktoken.get_encoding("cl100k_base")

client = OpenAI(
    api_key=os.environ["INFRAI_API_KEY"],
    base_url=os.environ["OPENAI_BASE_URL"],
    max_retries=0,
)

SUMMARY_SCHEMA = {
    "type": "object",
    "properties": {
        "summary": {"type": "string"},
        "facts": {"type": "array", "items": {"type": "string"}},
        "open_questions": {"type": "array", "items": {"type": "string"}},
        "source_chunk_ids": {"type": "array", "items": {"type": "integer"}},
    },
    "required": ["summary", "facts", "open_questions", "source_chunk_ids"],
    "additionalProperties": False,
}


def split_tokens(text: str) -> list[str]:
    tokens = ENCODING.encode(text)
    return [
        ENCODING.decode(tokens[start : start + MAX_CHUNK_TOKENS])
        for start in range(0, len(tokens), MAX_CHUNK_TOKENS)
    ]


def retry_after_seconds(error: RateLimitError, attempt: int) -> float:
    header = error.response.headers.get("retry-after")
    if header is not None:
        try:
            return max(0.0, float(header))
        except ValueError:
            pass
    return min(30.0, (2**attempt) + random.random())


def complete(messages: list[dict[str, str]], schema_name: str) -> dict[str, Any]:
    for attempt in range(MAX_RETRIES):
        try:
            response = client.chat.completions.create(
                model=MODEL,
                messages=messages,
                response_format={
                    "type": "json_schema",
                    "json_schema": {
                        "name": schema_name,
                        "strict": True,
                        "schema": SUMMARY_SCHEMA,
                    },
                },
            )
            content = response.choices[0].message.content
            if content is None:
                raise RuntimeError("The model returned no structured content")
            return json.loads(content)
        except RateLimitError as error:
            if attempt == MAX_RETRIES - 1:
                raise
            time.sleep(retry_after_seconds(error, attempt))
        except APIStatusError as error:
            body = error.response.text
            raise RuntimeError(f"API request failed with {error.status_code}: {body}") from error
    raise RuntimeError("Retry budget exhausted")


def summarize_document(text: str) -> dict[str, Any]:
    mapped = []
    for chunk_id, chunk in enumerate(split_tokens(text)):
        mapped.append(
            complete(
                [
                    {
                        "role": "system",
                        "content": (
                            "Summarize private developer documentation. Preserve negations, "
                            "limits, identifiers, and unresolved questions. Return only JSON."
                        ),
                    },
                    {
                        "role": "user",
                        "content": f"Source chunk ID: {chunk_id}\n\n{chunk}",
                    },
                ],
                "chunk_summary",
            )
        )

    return complete(
        [
            {
                "role": "system",
                "content": (
                    "Reduce validated chunk summaries into one answer. Remove duplicates, "
                    "preserve disagreements, and retain every supporting source chunk ID. "
                    "Return only JSON."
                ),
            },
            {"role": "user", "content": json.dumps(mapped)},
        ],
        "document_summary",
    )


if __name__ == "__main__":
    if len(sys.argv) != 2:
        raise SystemExit("Usage: python summarize.py DOCUMENT.txt")
    with open(sys.argv[1], encoding="utf-8") as source:
        result = summarize_document(source.read())
    print(json.dumps(result, indent=2))

There is no write operation in this critical path, so application-level idempotency keys are unnecessary. Retry behavior still needs care: only HTTP 429 is retried, Retry-After wins when present, and other API status errors surface their response body. A production worker should persist each validated map result under a deterministic document-version and chunk ID so a process restart does not pay for or recompute finished chunks.

The deliberately awkward cases deserve tests. An empty file should produce no map calls and should be handled before the reducer. A single chunk should still pass through reduction so its output contract matches larger documents. If mapped summaries themselves exceed the reducer's context budget, apply the same reduction recursively in bounded groups. No magic step appears at the top of the tree; it is map-reduce again.

Reject retrieval until selection is part of the product

The rejected first-version design is embeddings, vector search, rerank, map, and reduce for every document. It looks comprehensive, but it changes the job from “summarize all supplied text” to “summarize text the retrieval system selected.” That is not suitable when complete document coverage is an invariant, especially for private API references where one low-similarity warning can change the meaning of a feature.

Use that design when the valid use case changes: the user asks a focused question over a large knowledge base, processing every chunk would be wasteful, and relevance can be evaluated. At that point, embeddings form a candidate set and rerank orders the passages before the same validated summarization stages run. Keep source IDs through every hop. Otherwise, debugging a missing answer becomes a debate over three opaque stages.

This ADR leaves one clean upgrade path. Start with chunk counting, structured map outputs, provenance, and a reducer. Add retrieval only after observed queries establish the need. Short first. Correct throughout.

References

SMS OTP 2FA: Suppression Lists and Blocked Numbers in Transactional Auth Flows

mT41Gzp73rc6 — Thu, 20 Aug 2026 17:24:14 +0000

For a Node.js healthtech login, an SMS OTP 2FA flow must check suppression before delivery, preserve an audit trail, and withhold the session until the server verifies the code.

Short answer: SMS OTP 2FA is a reasonable choice for a normal SaaS authentication flow when suppression is checked before every send, blocked or unreachable numbers become explicit states, and verification is a server-side transaction rather than a client-side guess.

The recovery path matters just as much. This particular capability set has no voice, WhatsApp, or RCS channel, so recovery codes or a separately built email-code fallback need to exist before SMS goes live. Don't discover that boundary while a patient is locked out.

Treat the phone number as a delivery destination with policy state, not as proof of identity. Normalize it, associate it with the account, and check suppression before creating a challenge. A positive suppression result should stop the send and produce a stable application state such as blocked_number; it shouldn't fall through to a generic authentication failure.

Then create one short-lived challenge, send one OTP, and record the provider request identifier and timestamps in the audit record. Verification belongs on the server. Only a successful verification may consume the challenge and issue a session. An expired code, too many attempts, or a temporary rate limit must leave the user unauthenticated.

The ordering is deliberate:

Start an authentication transaction with a unique internal ID.
Check the SMS suppression list.
If allowed, create the OTP challenge and send the code.
Accept a code against that exact challenge.
Verify it server-side, consume the challenge once, and then issue the session.

No shortcuts.

For a compliance notice that accompanies login, keep notice delivery separate from authentication success. The audit record can say the notice was requested, accepted for delivery, later observed as delivered, or found unreachable. It must not claim that an accepted API request proves handset delivery. That distinction prevents a support agent from reading “sent” as “received,” and it keeps the login decision from becoming dependent on a vague messaging status.

How can a Node.js SMS OTP 2FA contract enforce suppression for blocked numbers?

Before writing an adapter, inspect the live capability contract rather than guessing its payload. This runnable script fetches the public discovery document through plain HTTP, checks the response status, handles HTTP 429 with bounded backoff, and confirms the method and path for suppression checks. Set INFRAI_API_BASE to the service API base and INFRAI_API_KEY to a secret from your environment.

import os
import time
from urllib.parse import quote

import requests


def read_contract(capability: str) -> dict:
    base_url = os.environ["INFRAI_API_BASE"].rstrip("/")
    api_key = os.environ["INFRAI_API_KEY"]
    url = f"{base_url}/v1/discovery/{quote(capability, safe='')}"

    for attempt in range(4):
        response = requests.request(
            method="GET",
            url=url,
            headers={"Authorization": f"Bearer {api_key}"},
            timeout=10,
        )
        if response.status_code != 429:
            break
        retry_after = response.headers.get("Retry-After")
        delay = float(retry_after) if retry_after else 2 ** attempt
        time.sleep(delay)
    else:
        raise RuntimeError("rate limit persisted after four attempts")

    if not response.ok:
        raise RuntimeError(f"contract request failed: {response.status_code} {response.text}")
    return response.json()


if __name__ == "__main__":
    contract = read_contract("sms.suppression.check")
    assert contract["method"] == "POST"
    assert contract["path"] == "/v1/sms/suppression/check"
    print(contract["params"])

The discovery response supplies the full JSON Schema in params, so the production adapter can validate its request against the current contract. It also exposes response schema, billing information, availability, and vendor readiness. That makes schema drift testable without turning this article into a copied endpoint manual.

A small state machine makes retries and support cases much easier to reason about. The following program is runnable as written. Its gateway is intentionally an in-memory test double because the verified API routes do not publish request fields in the material available here; inventing a JSON body would make the example dangerous to copy. A production adapter should map the same methods to the provider's documented schema.

from dataclasses import dataclass, field
from datetime import datetime, timedelta, timezone
from enum import Enum
from typing import Protocol
from uuid import uuid4


class AuthState(str, Enum):
    NEW = "new"
    BLOCKED_NUMBER = "blocked_number"
    CODE_SENT = "code_sent"
    VERIFIED = "verified"
    EXPIRED_CODE = "expired_code"
    TOO_MANY_ATTEMPTS = "too_many_attempts"
    RETRY_LATER = "retry_later"
    INVALID_CODE = "invalid_code"


class SmsGateway(Protocol):
    def is_suppressed(self, phone: str) -> bool: ...
    def create_otp(self, phone: str, idempotency_key: str) -> str: ...
    def verify_otp(self, challenge_id: str, code: str) -> bool: ...


@dataclass
class AuthTransaction:
    account_id: str
    phone: str
    id: str = field(default_factory=lambda: str(uuid4()))
    state: AuthState = AuthState.NEW
    challenge_id: str | None = None
    attempts: int = 0
    expires_at: datetime | None = None
    audit: list[dict[str, str]] = field(default_factory=list)

    def record(self, event: str) -> None:
        self.audit.append({
            "event": event,
            "at": datetime.now(timezone.utc).isoformat(),
        })


def begin(tx: AuthTransaction, gateway: SmsGateway) -> AuthState:
    if gateway.is_suppressed(tx.phone):
        tx.state = AuthState.BLOCKED_NUMBER
        tx.record("suppression_blocked")
        return tx.state

    tx.challenge_id = gateway.create_otp(tx.phone, idempotency_key=tx.id)
    tx.expires_at = datetime.now(timezone.utc) + timedelta(minutes=5)
    tx.state = AuthState.CODE_SENT
    tx.record("otp_requested")
    return tx.state


def verify(tx: AuthTransaction, gateway: SmsGateway, code: str) -> AuthState:
    if tx.state != AuthState.CODE_SENT or tx.challenge_id is None:
        raise ValueError("transaction is not ready for verification")
    if tx.expires_at is None or datetime.now(timezone.utc) >= tx.expires_at:
        tx.state = AuthState.EXPIRED_CODE
        tx.record("otp_expired")
        return tx.state
    if tx.attempts >= 5:
        tx.state = AuthState.TOO_MANY_ATTEMPTS
        tx.record("attempt_limit_reached")
        return tx.state

    tx.attempts += 1
    if gateway.verify_otp(tx.challenge_id, code):
        tx.state = AuthState.VERIFIED
        tx.record("otp_verified")
        return tx.state

    tx.state = AuthState.INVALID_CODE
    tx.record("otp_rejected")
    return tx.state


class DemoGateway:
    def is_suppressed(self, phone: str) -> bool:
        return phone.endswith("0000")

    def create_otp(self, phone: str, idempotency_key: str) -> str:
        return f"challenge:{idempotency_key}"

    def verify_otp(self, challenge_id: str, code: str) -> bool:
        return code == "123456"


if __name__ == "__main__":
    transaction = AuthTransaction(account_id="patient-42", phone="+15551234567")
    gateway = DemoGateway()
    begin(transaction, gateway)
    verify(transaction, gateway, "123456")
    assert transaction.state == AuthState.VERIFIED
    print(transaction.state.value)

The 5 attempt ceiling and five-minute lifetime are example application policy, not vendor defaults. Tune them against your threat model and support burden. Your mileage may vary — especially for users who travel, change SIMs, or share a household phone — but the invariant does not: no verified state, no session.

In a real adapter, every request needs an explicit HTTP method. Writes should carry an idempotency key, credentials belong in an environment variable, non-success responses need to surface their body, and HTTP 429 should honor Retry-After or use exponential backoff. Keep the same authentication transaction ID across a safe retry so a network timeout doesn't create two challenges.

Govern the audit evidence, not just the message

An auditable record should answer who initiated the action, which account and normalized destination it concerned, which policy decision ran, which provider request or challenge was created, and when each transition occurred. Store the destination carefully: support may need a masked form, while access to the full number should be limited according to the application's compliance design.

Record facts, not hopes. otp_requested means the provider accepted the request. otp_verified means the server accepted the submitted code. A later polled delivery event may add evidence about transport, but these systems expose events through polling rather than webhooks, so real-time multichannel orchestration is limited. Polling also needs a cursor or last-seen marker, bounded intervals, and idempotent event ingestion; otherwise the audit trail can duplicate events while still missing the distinction it was meant to preserve.

I wouldn't use an SMS delivery receipt as evidence that the intended person read a compliance notice. That conclusion isn't supported by transport status alone. The defensible record is narrower: what the application requested, what the messaging service reported, what code-verification decision the server made, and which session followed that decision.

Edge cases deserve named outcomes. blocked_number, too_many_attempts, expired_code, and retry_later give support something actionable without leaking whether an unrelated account exists. Repeated failures can also lead to suppression maintenance, but the threshold is an application policy decision. Geographic fences and per-country pricing circuit breakers are also application responsibilities here. Build them before opening international traffic.

Choose a provider only after defining recovery

Provider selection should follow the constraints above. Twilio Verify, Vonage Verify, and Sinch Verification are sensible products to evaluate alongside a unified API option, but this article does not have enough verified evidence to rank their delivery performance. Ask each candidate for current country coverage, sender-registration requirements, suppression semantics, retention controls, rate limits, event delivery model, and a schema you can pin in tests.

Option	Best fit	Limitation or validation point
Twilio Verify	Teams prepared to integrate a dedicated verification product	Validate current regional delivery, suppression, audit, and recovery behavior for the exact destination set
Vonage Verify	Teams comparing another dedicated verification contract	Validate sender rules, rate limits, event semantics, and data handling before rollout
Sinch Verification	Teams that want another direct verification-provider evaluation	Validate supported recovery channels and compliance evidence in each target country
Unified REST contract	Teams that value a stable application contract across underlying vendors	Confirm that polling-only events and the available channel set meet the recovery and timeliness requirements

The unified-contract option keeps the application contract fixed when the vendor behind a capability changes. Its public, self-describing discovery schema lets a deployment test the suppression contract before traffic moves.

Infrai uses one key for 295 routes across 20 modules and provides one bill for that capability surface. This means a single API key rather than one credential per provider, and a single invoice rather than a separate vendor reconciliation trail. Its REST API can be called directly over HTTP from any language, with no SDK to install. For this healthtech flow, those properties reduce credential rotation and make the messaging request easier to correlate during an audit.

The catch is material. This option is not suitable when webhook-driven orchestration, managed email OTP, SMTP relay, voice fallback, WhatsApp, or RCS is mandatory. Stick with a provider whose documented contract supplies the missing capability in those cases. Email fallback here requires a separately built email-code flow, and scheduled email does not have a cancellation operation.

Delivery reliability still can't be declared from a feature matrix. I'm not sure which candidate will perform best for a particular patient population without destination-level testing and current provider evidence. A controlled rollout, segmented by country and carrier where lawful, resolves that uncertainty more honestly than an overall success-rate claim.

Migrate one destination cohort at a time

Start with internal and consenting test accounts, including a suppressed destination, an unreachable number, an expired code, a sixth attempt, and an HTTP 429 path. Verify that every case lands in one support-friendly state and that no session exists before otp_verified. Then exercise retry behavior using the same transaction ID and confirm the audit log does not double-count the challenge.

Roll out by a small destination cohort and watch the outcomes separately: suppression blocks, request acceptance, polled delivery status, verification success, expiry, and recovery use. Keep the gateway interface narrow so changing providers affects the adapter, not authentication policy. This is the practical value of a stable contract — the risky decisions remain visible in your code, while transport can move behind it.

Finally, rehearse account recovery. Recovery codes should work when SMS cannot, and an email fallback must be owned and tested as its own authentication mechanism rather than treated as a free side effect of email delivery. There is no managed email OTP operation in this capability set.

Ship only when support can explain every state.

References

Reliable Password Reset Email Retries After 429 Responses (Without Duplicate Storms)

mT41Gzp73rc6 — Wed, 19 Aug 2026 05:40:56 +0000

Short answer: treat an email API 429 as backpressure, keep one durable delivery job per password-reset request, honor a valid Retry-After, and make the user cooldown independent from the worker retry schedule. The browser should receive the same neutral response whether an account exists, while a queue owns delivery attempts after the request ends.

The tempting implementation sends directly from the reset endpoint and lets the user request another message when it fails. That couples three clocks that have different jobs: the security lifetime of the reset token, the user-facing cooldown, and the provider-facing retry delay. Under throttling, those clocks turn one click into duplicate messages, old links, or a button that claims success while no durable work exists. Delivery reliability starts by separating them.

This pattern also fits an edtech receipt sent after payment settles. The payload and security stakes differ, but the operational rule is identical: commit the business event, create one durable notification job, then let delivery absorb provider backpressure without replaying the payment or inventing another receipt.

How should a password reset email API handle 429 rate limits?

Return from the public endpoint after recording intent, not after waiting for the email provider. For a reset request, create a random reset token, store only the verifier or digest needed to validate it, and enqueue a message that points to the current reset record. Do all of that in one database transaction where possible. If queue publication is separate, use an outbox row committed beside the reset record so a crashed process can't leave valid state with no delivery job.

Keep the public reply neutral. It shouldn't confirm that an address is registered, and a provider's 429 should never leak into the browser as a special account-dependent response. A typical response means only that the request was accepted for processing. The worker, not the user, handles transport pressure.

There are four distinct identifiers worth keeping:

A request ID follows one browser action through logs.
A reset ID names the current security operation for the account.
A delivery ID names one logical email and is the idempotency boundary.
A provider message ID, when available, correlates accepted mail with later delivery events.

Don't use the token string as an idempotency key or a log field. It is a credential. Use the delivery ID, and redact the reset URL from structured logs.

When the provider answers 429, parse Retry-After if it is valid and schedule the existing delivery job for that time. If it is absent or unusable, apply capped exponential backoff with jitter. Do not sleep inside a web process, hold a database transaction open, or create a fresh reset token merely because transport is throttled. A short-lived worker lease can expire; the durable next_attempt_at value cannot.

The repeat-request endpoint follows a different rule. During the cooldown it records no new delivery and returns the same neutral response. After the cooldown, it may rotate the reset operation and enqueue exactly one replacement message. Decide explicitly whether an older link remains valid. For password recovery, invalidating the previous reset when a replacement is issued gives the cleanest security rule, but the email copy must warn that only the newest link works.

That's the key split.

Model backpressure as durable state

A retry loop is easy to write and surprisingly easy to get wrong. The useful unit is not "call the API again"; it is a state transition guarded by a lease. One worker claims a due delivery, attempts it, then records accepted, retry_wait, or a terminal result. Another worker can reclaim an expired lease without creating another logical message.

The following Python sketch leaves transport and storage behind interfaces on purpose. Its important behavior is that a 429 reschedules the same delivery ID, caps delay, adds jitter, and consumes a retry budget. The public request handler never runs this loop.

from dataclasses import dataclass
from datetime import datetime, timedelta, timezone
import random


@dataclass(frozen=True)
class Delivery:
    delivery_id: str
    attempts: int
    expires_at: datetime


def retry_delay(attempts: int, retry_after_seconds: int | None) -> timedelta:
    if retry_after_seconds is not None and retry_after_seconds >= 0:
        seconds = min(retry_after_seconds, 15 * 60)
    else:
        base = min(2 ** attempts, 15 * 60)
        seconds = random.uniform(base * 0.5, base)
    return timedelta(seconds=seconds)


def deliver_once(delivery: Delivery, mailer, store) -> None:
    now = datetime.now(timezone.utc)
    if now >= delivery.expires_at:
        store.mark_expired(delivery.delivery_id)
        return

    result = mailer.send(delivery.delivery_id)
    if result.accepted:
        store.mark_accepted(delivery.delivery_id, result.message_id)
        return

    if result.status_code == 429:
        delay = retry_delay(delivery.attempts, result.retry_after_seconds)
        next_attempt = min(now + delay, delivery.expires_at)
        store.reschedule(delivery.delivery_id, next_attempt)
        return

    store.apply_failure_policy(delivery.delivery_id, result.category)

Production code needs a stricter parser around Retry-After, an atomic claim operation, and a maximum-attempt policy. It also needs to distinguish a retryable transport response from a permanent recipient or policy rejection. I'm not sure one universal retry budget exists; the right number depends on token lifetime, provider contract, queue latency, and the recovery path available to the learner. Those inputs should be configuration reviewed with security and support, not magic constants copied from an SDK sample.

Avoid a subtle expiry mistake in the sketch: if next_attempt equals token expiry, there may be no useful time left to deliver and click. Set a final-attempt cutoff earlier than expiry, with room for normal inbox delay. Once that cutoff passes, mark the delivery expired and let a new user action create a new reset operation. Endless retrying is not reliability.

For an order receipt, the terminal policy changes. A receipt doesn't become a security liability when its link ages, so the job can remain recoverable longer; the payment event still must never be replayed. This is why notification state belongs beside, but not inside, the business transaction.

Make duplicates harmless before tuning retries

An idempotency key helps only if every layer agrees on its scope. The database should reject a second active delivery for the same reset generation. The queue should tolerate at-least-once execution. The mail adapter should pass a stable logical identifier if its contract supports one. If it doesn't, the worker still needs an atomic state transition before and after the call, plus reconciliation for the narrow uncertainty window where the remote side accepts a message and the worker loses its acknowledgement.

That uncertainty cannot be erased by prettier backoff math.

Design the email so duplicates are survivable. Both copies should point to the same current reset operation until a deliberate replacement request rotates it; redemption must be single-use; and a successful password change must invalidate the operation. Never put the recipient address, token, or complete reset URL into metrics labels. High-cardinality secrets are still secrets.

The repeat-request cooldown protects both people and infrastructure, but it is not the same as a per-IP abuse limit. Apply layered controls to the account key, a privacy-preserving network signal, and broader system capacity. Keep responses uniform enough that timing and wording don't become an account-discovery side channel. Also provide a support route for learners who have lost access to the mailbox. A cooldown with no recovery path becomes a lockout mechanism.

Password reset mail is transactional, so don't casually attach marketing content or mailing-list controls to it. RFC 8058 defines one-click unsubscribe behavior for list mail; it is useful at the boundary where a message really is subscription traffic, not as decoration on a security message. Keep those streams and their consent records separate.

SMS fallback deserves the same boundary discipline. The WebOTP API can help a browser receive an SMS-formatted one-time code after user consent, but it doesn't turn SMS into email delivery confirmation or justify silently changing recovery channels. Channel enrollment, disclosure, rate limits, and account-recovery policy still apply.

Observe the state machine, not just API latency

An email API returning quickly tells you very little about whether the learner can reset a password. Measure counts and age by state: queued, leased, accepted by transport, delivered when trustworthy event data exists, retrying after 429, permanently rejected, expired, and redeemed. The most useful alarm is often the age of the oldest eligible delivery, because a calm request rate can hide a stuck queue.

Log transitions with request ID, delivery ID, attempt number, normalized outcome category, scheduled retry time, and provider message ID. Leave the address and token out. Track the ratio of reset requests to accepted deliveries and successful redemptions, but interpret it carefully: users can request a reset and then remember their password. Your mileage may vary across school calendars, shared family inboxes, and institutional mail filters.

Test ugly sequences before deployment — two repeat clicks at the cooldown boundary, two workers claiming the same job, a 429 with no usable delay, process loss after remote acceptance, token redemption during a retry wait, and a replacement request while an older email is in flight. Use a fake clock and scripted mail adapter so every transition is deterministic. Then run a small canary with dashboards already open.

No heroics.

Roll out with explicit limits

Start by putting durable jobs behind the existing request endpoint without changing the email template. Next, introduce stable delivery IDs and state metrics. Only then enable scheduled 429 retries and the separate user cooldown. This sequence makes each behavioral change observable and gives rollback a narrow surface.

The catch is operational weight. A database-backed outbox, worker leases, reconciliation, and delivery-event ingestion are not suitable when the message is genuinely best-effort and carries no security or financial consequence. For a tiny internal tool, stick with a simpler queued sender and accept manual recovery. For password resets and settled-payment receipts, the durable state machine earns its keep because losing intent or multiplying messages creates support and trust problems that a faster API call cannot repair.

Choose limits from the actual token lifetime, provider guidance, and support promise. Document who owns exhausted jobs, how a learner recovers, and what constitutes delivery success. A reliable reset flow doesn't promise that every mailbox will accept every message. It promises that backpressure is controlled, duplicates are bounded, secrets stay out of telemetry, and failure ends in a visible state rather than a vanished request.

DEV Community: mT41Gzp73rc6

Password Reset Email Architecture: Node.js Token Links, DKIM/SPF, and API Boundaries

Decision record: invariants and failure boundaries

How should a password reset email flow in Node.js handle API tokens and links?

What do custom-domain SPF, DKIM, and DMARC actually guarantee?

Which delivery boundary should the architecture choose?

Rejected option and its valid use case

References

Simplest Email Deliverability Service for Small SaaS: Domains, Suppression, and Polling

What audit trail does an order notification need?

How should a small SaaS handle custom-domain email deliverability, suppression, and bounce polling?

What governance evidence should the provider leave behind?

How do the options differ for this order workflow?

How can a canary test the recovery loop?

References

Shared-Device Authentication: Session Isolation During Safe Account Switching and Deletion

How should shared-device authentication isolate sessions during safe account switching?

The boundary is the migration contract

A minimal deletion flow over HTTP

Compare providers against the contract, not the login screen

Roll out with destructive tests first

References

Automotive Login Defense — Secure SMS OTP Flow with Replay and Lockout Controls

The bill follows attempts; the audit trail follows decisions

How can an automotive SaaS stop SMS OTP replay in the US and EU?

Which provider model matches the work your backend should own?

Reliability after a lost response depends on stable identity

Compliance evidence is a bounded record, not a transcript

References

Further reading

SaaS Event Alert Emails: Custom Domains, DKIM, Templates, and Deliverability

Start with the invariant, not the provider

How should a SaaS team handle custom domains, DKIM, templates, and deliverability?

A deliverability loop that survives real events

What template ownership changes in practice

A compact rollout decision

References

Node.js Contact-Form Routing: API-Poll Transactional Email Before SMS Fallback

How should a Node.js event-notification service poll transactional email delivery status before an SMS fallback?

Keep contact-form routing separate from channel delivery

What does a delivery-status polling implementation need to handle?

Which integration trade-offs matter for this fallback design?

Roll out the fallback in small, observable steps

References

Generated Health Reports: Troubleshooting Stuck Batch Sends with Recipient Status Polling

What actually drives cost and retention?

How should batch email and SMS polling handle each recipient's status?

A replaceable reconciliation boundary

Where does each provider choice fit?

References

5 Reliability Checks for Custom Sending Domains and DKIM Rotation in Email APIs

1. What happens during a 30-minute order-email rehearsal?

2. How can a Node.js worker replay one order email safely?

3. What release decision keeps a marketplace notification available?

4. How can a Node.js email API verify SPF and DKIM before DMARC-aware rotation?

5. Can overlapping DKIM selectors protect retries?

References

Password Reset Email API: 7 Custom HTML and Suppression Reliability States

Data retention rules for seven durable states

How can a Next.js API route test password reset email?

Compare five provider candidates with one fixture

Retry and failure handling in Python

When to reject synchronous delivery semantics

References

How to Build a 2-Stage Long Document Summarization API with Chunking

What invariants should a long document summarization API preserve during chunking and map reduce?

Where should embeddings and rerank enter the pipeline?

Record the provider decision without turning it into architecture

Implement the two-stage critical path

Reject retrieval until selection is part of the product

References

SMS OTP 2FA: Suppression Lists and Blocked Numbers in Transactional Auth Flows

How can a Node.js SMS OTP 2FA contract enforce suppression for blocked numbers?

Govern the audit evidence, not just the message

Choose a provider only after defining recovery

Migrate one destination cohort at a time

References

Reliable Password Reset Email Retries After 429 Responses (Without Duplicate Storms)

How should a password reset email API handle 429 rate limits?

Model backpressure as durable state