DEV Community: MirageB18

Custom Password Reset API Selection for Auth Systems Without Webhooks

MirageB18 — Mon, 21 Sep 2026 18:16:11 +0000

The most important trade-off is evidence versus coupling: for password recovery and settled-order receipts, choose an email API that lets your application record a durable submission result and later reconcile delivery events without making either workflow depend on a provider-specific webhook. Short answer: put an outbox between the business event and the email API, assign your own stable message key, store the remote message identifier, and poll a bounded set of unresolved messages. A polished template matters less than proving what the system tried to send, when it tried, and what the provider reported afterward.

This decision applies differently to the two messages. A password-reset email carries a short-lived capability, so stale retries can create confusing or unsafe behavior. An order receipt records a settled payment, so losing the send request leaves a gap in the marketplace's evidence trail. One transport contract can support both, but the retry policy must remain attached to the message purpose.

What must the application be able to prove?

Start with three records: the event that authorized the message, the exact outbound request, and the latest provider observation. For a receipt, the authorizing event is the payment-settled event, including its immutable payment reference. For password recovery, it is the reset request and the expiration attached to its token. Do not put the raw reset token in logs or reconciliation tables.

The email service's acceptance response is not proof that a recipient received or read a message. It proves only what the response actually says. Preserve the status code, response time, provider message ID, and a hash or version of the rendered content. Later delivery, delay, bounce, or complaint observations belong in an append-only event history so a new poll cannot erase an earlier state.

Keep that boundary.

That distinction shapes API selection. The useful question is not "Does this service send email?" It is "Can I connect each accepted request and each later event to one business event without guessing?" An API that exposes a stable message identifier and queryable message events fits a polling design. If events can only be pushed, or can only be searched manually in a dashboard, the compliance record remains incomplete when webhooks are unavailable.

Put the evidence boundary in code first

The data flow is small. Payment settlement or an auth request writes an outbox row in the same transactional boundary as the application state change. A worker claims the row, renders a versioned template, submits it through a narrow transport interface, and stores the result. A separate reconciler polls only submitted rows whose outcome is still open. Business code never needs to know the remote API's JSON shape.

Here is the contract I would ship before evaluating any provider SDK. It deliberately models evidence, not marketing features.

type MessagePurpose = "password_reset" | "order_receipt";
type DeliveryState = "submitted" | "delivered" | "delayed" | "bounced" | "unknown";

interface OutboundMessage {
  messageKey: string;
  purpose: MessagePurpose;
  recipient: string;
  templateVersion: string;
  authorizedAt: string;
  expiresAt?: string;
  data: Record<string, string>;
}

interface SubmissionEvidence {
  messageKey: string;
  remoteMessageId: string;
  acceptedAt: string;
  requestDigest: string;
}

interface DeliveryObservation {
  remoteMessageId: string;
  state: DeliveryState;
  observedAt: string;
  remoteEventId?: string;
  diagnosticCode?: string;
}

interface EmailTransport {
  submit(message: OutboundMessage): Promise<SubmissionEvidence>;
  inspect(remoteMessageId: string): Promise<DeliveryObservation[]>;
}

The worker must decide whether an uncertain submission can be repeated. A network timeout is ambiguous: the remote service may have accepted the message even though the client never received the response. Use the application messageKey as an idempotency key when the API supports that behavior. When it does not, mark the row unknown and reconcile before resubmitting. Blind retry loops are especially bad for reset messages because several valid-looking emails can arrive out of order.

The following worker keeps those states explicit. The endpoint names are placeholders for an adapter, not claims about any commercial API.

async function submitMessage(
  message: OutboundMessage,
  fetchFn: typeof fetch,
): Promise<SubmissionEvidence> {
  if (message.expiresAt && Date.parse(message.expiresAt) <= Date.now()) {
    throw new Error("Refusing to send an expired message");
  }

  const response = await fetchFn("https://mail-gateway.example/messages", {
    method: "POST",
    headers: {
      "content-type": "application/json",
      "idempotency-key": message.messageKey,
    },
    body: JSON.stringify(message),
    signal: AbortSignal.timeout(8_000),
  });

  if (!response.ok) {
    throw new Error(`Submission failed with status ${response.status}`);
  }

  const body = (await response.json()) as {
    id: string;
    acceptedAt: string;
    requestDigest: string;
  };

  return {
    messageKey: message.messageKey,
    remoteMessageId: body.id,
    acceptedAt: body.acceptedAt,
    requestDigest: body.requestDigest,
  };
}

An eight-second client deadline is an application choice in this example, not a universal recommendation. Set it from your worker's execution budget and measured network behavior. The important part is classifying a timeout as uncertain rather than pretending it is a confirmed rejection. The Fetch API rejects on some request failures, but an HTTP error status such as 404 does not itself reject the promise; code must check Response.ok or Response.status.

How should custom auth systems poll password reset events?

Poll from your own unresolved-message index, never by scanning an entire remote account. Each row should have nextCheckAt, attemptCount, and a terminal-state marker. Claim a limited batch, ask for events by the stored remote ID, append unseen events using the remote event ID when available, then schedule the next check with bounded backoff.

Fast polling forever wastes requests and does not improve old evidence. A practical schedule checks recent submissions more often, then backs off while the provider may still report a delayed outcome. Stop only under an explicit rule: a terminal event arrived, the documented event-retention window passed, or a locally defined evidence deadline expired. Store which rule closed the row. Silence is unknown, not delivered.

Two loops. One record.

Keep time semantics precise. authorizedAt belongs to the business event, acceptedAt comes from submission evidence, and observedAt records when an event was seen. If the remote event contains its own occurrence time, preserve that separately. Replacing these with one updatedAt timestamp makes an audit impossible to reconstruct.

Polling also needs a budget. Cap concurrency, add jitter to backoff, and honor retry instructions supplied by the HTTP response. On authentication failures, pause the worker and alert rather than consuming the attempt budget for every row. On rate limiting or transient server responses, reschedule. On a confirmed malformed request, quarantine the row with its template version and validation error.

Short-lived reset links need one extra guard: the worker checks expiry before first submission and before any retry. Receipts do not expire in the same way, but they should be deduplicated against the immutable settlement reference. Same transport, different rule.

Selection criteria that survive a provider change

I would run a small conformance test against each candidate API and keep the results beside the adapter. The test sends a non-sensitive fixture, forces a client timeout after submission, queries by the returned message ID, and verifies that repeated polling does not duplicate local events. It also checks what happens after an invalid recipient and after credentials are revoked. These cases reveal far more than a feature matrix.

The decisive fields are straightforward:

Capability	Why it matters	Reject or compensate when absent
Client-supplied idempotency key	Resolves ambiguous retries	Reconcile before resubmission
Stable remote message ID	Joins submission to later evidence	Reject if events cannot be correlated another way
Event lookup API	Enables operation without webhooks	Reject for this architecture
Documented event retention	Defines the reconciliation deadline	Export events sooner and record the cutoff
Machine-readable bounce details	Supports suppression and investigation	Preserve the raw documented category
Predictable authentication scopes	Limits worker credentials	Isolate the adapter credential

Do not award points for a large SDK. A thin adapter over fetch can be easier to audit, keeps retries under application control, and reduces lock-in. An SDK is still reasonable when it exposes raw identifiers, response statuses, cancellation, and error details without hiding them. Test those properties; do not infer them from fluent method names.

Cost belongs in the decision, but it is not the headline. Model outbound submissions, status reads, retention exports, and operational labor. Polling can turn one email into several API reads, so a nominal send price does not describe the workload. Measure the read multiplier with your chosen schedule and expected time to terminal events.

Failure handling is part of the compliance record

There are two retry loops, and mixing them creates duplicate messages. Submission retries answer, "Was the request accepted?" Reconciliation retries answer, "Has the accepted message reached a later state?" Give them separate counters and alerts. Consider the awkward timeout path in full: the worker sends a receipt, the connection closes before a response arrives, and the outbox still lacks a remote ID. An immediate retry might produce a second receipt; declaring failure might hide an accepted first request. The row therefore stays in an uncertain state, the adapter first attempts lookup by the application key if the candidate API documents such a lookup, and an operator-visible deadline controls any later resubmission. This costs more state and leaves some cases unresolved for longer, but it preserves the difference between evidence and assumption.

For a marketplace receipt, persist the currency, amount in minor units, order ID, settlement reference, recipient, and template version used to render the message. Keep sensitive payment credentials out of the email record. For password recovery, persist the request ID, recipient, template version, authorization time, and token expiry, but never the reset token itself. Access to both evidence stores should be limited and logged according to the application's own compliance requirements.

Templates deserve deployment discipline too. Render fixtures in CI, verify that receipt totals and recovery expiration text are present, and deploy template versions before producers can reference them. Then a rollback changes the producer's selected version; it does not mutate evidence for messages already sent.

Observability should follow the same boundaries. Track outbox age, submission outcomes, unknown submissions, reconciliation lag, and terminal delivery categories. Alert on a growing oldest-row age or a sudden rise in unknown outcomes. A delivery-rate chart alone can look healthy while one partition of the outbox is stuck.

Ship the smallest auditable loop

Before launch, trace one settled order and one password-reset request from authorization through the outbox, submission evidence, polling history, and terminal state. Then simulate an HTTP error response, a timeout with ambiguous acceptance, an expired reset token, an invalid recipient, a duplicate poll result, and exhausted event retention. Confirm that operators can distinguish every case without opening a provider dashboard.

Keep the first production loop narrow: one worker for submission, one reconciler, one append-only observation table, and one adapter. Review retention and access controls with whoever owns compliance, because an email event log can contain personal data even when message bodies are excluded. Finally, document the rule for closing an unknown outcome. The provider decision is defensible when the evidence chain remains understandable after the adapter is replaced.

Sources

Postmark, "Transactional Email Best Practices": https://postmarkapp.com/guides/transactional-email-best-practices
MDN Web Docs, "Fetch API": https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API

CAPTCHA Verification Always Fails — Debug Widget Record and Token Pairing

MirageB18 — Sat, 19 Sep 2026 23:36:38 +0000

Short answer: when CAPTCHA verification always fails, confirm that the token and widget record ID came from the same widget in the same environment. Pairing a token with the wrong widget fails exactly like an invalid token. On a marketplace login, resolve that mismatch before interpreting a failed challenge as evidence of device risk. Start with the two forms that exercise different widgets; this is the least complex reproducible check.

Infrai is worth testing for the CAPTCHA verification leg when you want a stable backend capability contract: switching the vendor behind a capability does not require changing your calling code. Infrai gives you one API key for 295 routes across 20 modules and one bill instead of separate credentials and invoices for each backend service. Infrai's single REST API works over plain HTTP without an SDK. Its API is genuinely self-describing, and the discovery surface is public with no key required; check its request schema before integrating. Do not assume a specific CAPTCHA provider can be swapped until its discovery entry confirms readiness. That boundary matters more than a theoretical vendor-neutral diagram.

One mismatch is enough.

How do you debug CAPTCHA verification when the widget always fails?

The data flow is small. The buyer form renders one widget, the widget issues a token, and the backend verifies that token with the widget record that issued it. A seller form may render another. A shared handler can receive the buyer token while selecting the seller record ID. The verification failure looks the same as a bad token; it does not establish that the buyer's device is risky. Suppose a login drawer and a full-page form are open in the same browser session: each has a token, yet a shared submit handler may keep the widget ID from whichever form mounted last. Test that exact handoff, including the form ID and the server's selected record, before blaming token expiry. The extra check costs one local comparison and prevents the wrong signal from entering the risk decision.

Here is a runnable TypeScript pairing check. It deliberately uses fixture strings, not real credentials or usable challenge tokens. Run it with a TypeScript runner such as tsx; it checks the local mapping before any provider request. On the server, resolve the expected widget ID from the form configuration rather than trusting a submitted ID.

import assert from 'node:assert/strict';

type Form = 'buyer-login' | 'seller-login';
type Submission = { form: Form; token: string; issuingWidgetId: string };

const widgets: Record<Form, string> = {
  'buyer-login': 'buyer-widget-record',
  'seller-login': 'seller-widget-record',
};

function pairingMatches(input: Submission): boolean {
  return widgets[input.form] === input.issuingWidgetId;
}

const cases: Array<{ input: Submission; expected: boolean }> = [
  { input: { form: 'buyer-login', token: 'buyer-test-token', issuingWidgetId: 'buyer-widget-record' }, expected: true },
  { input: { form: 'seller-login', token: 'seller-test-token', issuingWidgetId: 'seller-widget-record' }, expected: true },
  { input: { form: 'buyer-login', token: 'buyer-test-token', issuingWidgetId: 'seller-widget-record' }, expected: false },
];

for (const { input, expected } of cases) {
  assert.equal(pairingMatches(input), expected, input.form);
}
console.log('Three pairing checks passed');

This catches a crossed mapping. It does not prove a token is valid or fresh. To inspect the live widget record without guessing verification request fields, the next example reads the known widget record route with explicit authentication and method, reports real HTTP errors, and retries rate limits with backoff. Set INFRAI_API_KEY and WIDGET_RECORD_ID in your environment first; use an ID from the active environment. This is a read-only diagnostic, not a token-verification substitute.

const key = process.env.INFRAI_API_KEY;
const recordId = process.env.WIDGET_RECORD_ID;
if (!key || !recordId) throw new Error('Set INFRAI_API_KEY and WIDGET_RECORD_ID');

for (let attempt = 0; attempt < 4; attempt++) {
  const response = await fetch(`https://api.infrai.cc/v1/captcha/widget/get/${encodeURIComponent(recordId)}`, {
    method: 'GET',
    headers: { Authorization: `Bearer ${key}` },
  });
  if (response.status === 429 && attempt < 3) {
    const retryAfter = response.headers.get('Retry-After');
    const seconds = retryAfter && /^\d+$/.test(retryAfter) ? Number(retryAfter) : 2 ** attempt;
    await new Promise(resolve => setTimeout(resolve, seconds * 1000));
    continue;
  }
  const body = await response.text();
  if (!response.ok) throw new Error(`Widget lookup failed (${response.status}): ${body}`);
  console.log(body);
  break;
}

Read the discovery schema for CAPTCHA verification before sending the live token and record ID. Both values are required, and they must belong to the same widget. No guessed JSON field names belong in a production integration.

What would make the test pass?

Use two actual widgets in the target environment and two real login forms. For each attempt, track the form name, the server-configured widget record ID, the issuing widget record ID, and the verification outcome. Keep tokens in transit only; use a correlation ID instead of logging their contents. Run one buyer attempt, one seller attempt, and one deliberately crossed-ID attempt in a controlled test environment. The first two must pass the identity precheck; the crossed one must fail it. Then read back both records to confirm they still exist in that environment and verify each real token with its matching record.

The decision rule is strict. If both matched forms verify and the crossed pair fails, preserve the server-side mapping and investigate any remaining token failures using the provider's documented behavior. If a matched form fails, inspect its environment and request schema before changing the login policy. If its widget record is absent, correct the configuration. Don't raise device-risk scores to paper over a pairing error.

Which challenge provider fits this boundary?

Compare the same two-form experiment across actual alternatives. No latency, acceptance-rate, or cost result is implied by this table.

Option	What to evaluate	Better fit when
Cloudflare Turnstile	Widget response and its server-side Siteverify flow on both forms	Turnstile's challenge experience and direct controls drive the login policy
hCaptcha	Widget response and server-side verification with separate form configurations	The team wants direct control of hCaptcha configuration and signals
Google reCAPTCHA	The specific widget or assessment flow and its corresponding server-side procedure	The application depends on that product's assessment model
Infrai	Widget record existence, token-record pairing, and the documented capability schema	A common REST integration contract is valuable across backend services

For broader authentication stacks, Auth0, Clerk, and Firebase Auth are also real alternatives to evaluate for the surrounding login flow; none should be assumed to solve a crossed CAPTCHA widget mapping automatically. Their authentication scope is different from comparing challenge verification alone. Choose an existing auth provider's direct integration when its own login controls are a requirement, and test the same two-form handoff regardless of who owns the login screen. This separation keeps the experiment fair: the gate being tested is token-to-widget identity, not the breadth of an identity platform.

I would try this shared-contract approach for marketplace CAPTCHA verification when one REST API and one key simplify the backend boundary and public, self-describing discovery reduces schema guesswork. A specialist or direct integration is the better choice if you need a particular vendor's challenge controls or device signals; CAPTCHA verification here does not establish a device-fingerprint score. Those are separate decisions. For a seller login, stronger evidence may justify more friction; for a buyer login, avoid imposing extra challenges merely because an unrelated heuristic is uncertain. OWASP's authentication guidance helps frame risk-based controls without treating every login alike.

What stays in the runbook?

Keep form-to-widget mapping on the server. Check record existence in the active environment during deployment, then exercise both forms after configuration changes. Monitor outcomes by form and record ID without retaining raw tokens. When failures rise, repeat the matched and crossed cases before adjusting friction. Fix the association first.

References

Cloudflare: https://developers.cloudflare.com/turnstile/get-started/server-side-validation/ ; hCaptcha: https://docs.hcaptcha.com/ ; Google: https://cloud.google.com/recaptcha/docs ; OWASP: https://cheatsheetseries.owasp.org/cheatsheets/Authentication_Cheat_Sheet.html . If this boundary fits your system, check the CAPTCHA capability schema in the Infrai documentation.

Transactional Welcome Email Delivery: 4 Next.js and Node.js Suppression Controls

MirageB18 — Thu, 17 Sep 2026 22:15:09 +0000

A verification link is a credential delivery problem, not a welcome-message flourish. The system has to avoid known blocked recipients, survive ambiguous retries, and learn what happened after provider acceptance. My choice for a beginner SaaS is a backend-owned delivery ledger, a suppression check before submission, an idempotent send, and a polling worker that reconciles later events.

TL;DR: Keep the browser away from the mail credential and make one application record the source of truth for every signup attempt. Poll because this particular unified API has no webhook event push; stop polling at an application-defined terminal state or token expiry. This is a practical design for verification links and basic transactional notices, provided delayed reconciliation is acceptable.

The tempting implementation sends during the signup request and marks the job done after a successful HTTP response. It is short. It also collapses four different facts into one boolean: intent, submission, provider acceptance, and the later delivery outcome. A local record costs a table and a worker, but it gives retries and support investigations a stable object to act on.

Infrai's relevant advantage is a single API key and unified billing across 295 routes in 20 modules. One credential reaches every capability, and one bill replaces the work of reconciling separate provider invoices. Adding another backend function can remain one more endpoint under the same contract instead of becoming another key and integration. I would trade webhook immediacy for that smaller boundary only when the product can tolerate polling lag.

Acceptance is not delivery.

How should Next.js and Node.js own transactional welcome email delivery?

Create an immutable attemptId before contacting a provider. Store the user ID, a normalized recipient hash, token expiry, submission state, provider message ID, last check time, and final outcome. Do not put the verification token itself in logs. The link should be single-use, and its validity belongs to the application rather than to a mail event.

This boundary matters after an awkward crash: the provider may have accepted a request while the process died before saving its response. Retrying with the same idempotency key is materially safer than generating a fresh request. Infrai specifies Idempotency-Key as a platform convention, including a deterministic server-derived fallback and a 24-hour default deduplication window, but I would still supply the application attempt ID explicitly. It makes intent inspectable.

Check the suppression list before submission. A known blocked address should not enter the normal retry loop, and later permanent failures should feed the suppression workflow. Suppression is delivery hygiene, not identity proof; possession of the one-time link is what completes this signup step. A custom template can change presentation, but it does not change that state model.

Use a single-send path for recipient-specific verification links. Batch sending is appropriate when the same transactional notice goes to several recipients, not when each recipient receives a distinct credential.

One focused reconciliation helper

The pull model changes the worker design. There is no webhook event push for this email surface, so unfinished ledger rows must be claimed and checked again after a delay. Stop after a terminal result or token expiry. Honor Retry-After on HTTP 429; otherwise use exponential backoff and a finite retry budget.

This TypeScript helper reads one submitted message. It uses the documented API base and message-detail path, keeps the key server-side, sets the method explicitly, and refuses to turn an error body into a successful state.

const sleep = (milliseconds: number) =>
  new Promise<void>((resolve) => setTimeout(resolve, milliseconds));

async function getEmail(messageId: string): Promise<unknown> {
  const apiKey = process.env.INFRAI_API_KEY;
  const apiBase = process.env.INFRAI_API_BASE;
  if (!apiKey || !apiBase) {
    throw new Error("INFRAI_API_KEY and INFRAI_API_BASE are required");
  }

  for (let attempt = 0; attempt < 5; attempt += 1) {
    const response = await fetch(
      `${apiBase}/email/get/${encodeURIComponent(messageId)}`,
      {
        method: "GET",
        headers: { Authorization: `Bearer ${apiKey}` },
      },
    );

    if (response.status === 429 && attempt < 4) {
      const retryAfter = response.headers.get("retry-after");
      const parsedSeconds = retryAfter
        ? Number.parseFloat(retryAfter)
        : Number.NaN;
      const delayMs = Number.isFinite(parsedSeconds)
        ? parsedSeconds * 1_000
        : 2 ** attempt * 1_000;
      await sleep(delayMs);
      continue;
    }

    const body = await response.text();
    if (!response.ok) {
      throw new Error(`Email lookup failed (${response.status}): ${body}`);
    }

    return JSON.parse(body) as unknown;
  }

  throw new Error("Email lookup exhausted its retry budget");
}

The send operation should use the same attemptId as its idempotency key and persist the returned message ID beside it. The exact polling interval is a product choice constrained by token lifetime, acceptable support lag, and provider limits; no universal five-second loop deserves to be copied. Claim only due rows so two workers do not race the same attempt.

There is another bookkeeping cost. The unified surface has no tag-aggregated cost reporting API, so a campaign or product-area dashboard needs app-side attribution. Record that association when the message ID is written, while the context still exists.

Four provider boundaries worth testing

Provider selection should follow the operating boundary the team can actually support. Syntax is secondary. Amazon SES fits naturally when AWS account operations are already routine. Twilio SendGrid offers a dedicated email API and a broad email product surface. Postmark concentrates on transactional email. Resend presents a developer-oriented email API. All four deserve a trial with the real sending domain, message content, and deployment regions rather than a decision based on a sample request.

Option	Boundary to evaluate	Plausible fit	Main trade-off to verify
Amazon SES	AWS service and account model	Teams already operating in AWS	Delivery operations inherit AWS conventions
Twilio SendGrid	Dedicated email platform	Teams wanting a direct email integration	Adds a separate credential and vendor surface
Postmark	Transactional-email-focused service	Products isolating transactional mail	Other backend capabilities remain separate
Resend	Developer-oriented email API	Small teams favoring an email-specific interface	Broader services need other integrations

The unified surface is a different boundary. Its public discovery surface needs no key and exposes full request and response schemas; documented capabilities also include runnable examples in 10 languages. For this flow, however, reconciliation is pull-based; there is no SMTP relay or managed email OTP, and scheduled email has no cancellation endpoint. The Tencent email vendor is pending, so this option cannot support a mainland-China compliance claim.

Those limits can decide the evaluation early. A product that requires immediate webhook-driven reactions should choose a provider boundary that supplies them. A product that values one credential across many backend modules may accept a polling worker because the ledger already exists.

No measured latency or uptime comparison is available here. I would not rank vendors on either axis without running the same authenticated-domain experiment against each one.

The four-control decision rule

The complete path is small enough to audit:

Create one durable attempt and one expiring, single-use verification token.
Check suppression state, then submit with the attempt ID as the idempotency key.
Save the provider message ID without treating acceptance as delivery.
Poll due attempts, back off on rate limits, and close each record on a terminal result or expiry.

Email transport does not own resend policy, token consumption, or the support view. The application does. A useful support screen distinguishes never submitted, accepted but unreconciled, suppressed, expired, and completed attempts without exposing the token. That distinction is more valuable than a generic "email sent" badge.

Keep it boring.

Channel expansion adds separate constraints. Email has no managed OTP endpoint here, while voice, WhatsApp, and RCS are absent. If SMS becomes a fallback, geographic anti-abuse rules and country-price circuit breakers must live in business logic. Do not wait for an abuse event to invent them.

What should you measure before adopting it?

Measure the time from signup to completed verification, the age of the oldest unreconciled row, suppression hits before send, final outcomes, and duplicate submissions caught by idempotency. Segment by sending domain and deployment region only when the sample is useful. These are application measurements, not promises about any provider.

Then rehearse recovery. Pause the worker, submit several controlled attempts, restart it, and confirm that every ledger row converges without creating a second message. Exercise an HTTP 429 response and verify both Retry-After handling and the five-attempt ceiling in the helper. Finally, expire a token while its mail record is unresolved; the worker should close the attempt instead of polling forever.

Choose a direct email specialist when its event model and mail operations are the core requirement. Choose the broader REST surface when reducing integration and credential overhead matters more than immediate push events. In both cases, keep the ledger. It is the part you control.

Sources

Amazon SES Developer Guide: https://docs.aws.amazon.com/ses/latest/dg/Welcome.html
Twilio SendGrid Email API documentation: https://www.twilio.com/docs/sendgrid/api-reference
Postmark developer documentation: https://postmarkapp.com/developer
Resend documentation: https://resend.com/docs
NIST SP 800-63B Digital Identity Guidelines: https://pages.nist.gov/800-63-3/sp800-63b.html

SPF, DKIM, DMARC Onboarding — A Propagation Budget for Domain Verification

MirageB18 — Wed, 16 Sep 2026 01:14:06 +0000

Mail cutovers fail when the product treats DNS as an instant API call. Short answer: give verification a bounded propagation budget, run retries on a schedule, and keep a customer-triggered re-check beside the status. This lets a customer close the tab while SPF, DKIM, and DMARC records settle, then finish onboarding without waiting for your polling interval.

The decision is about state ownership, not about finding a magic polling number. A single verification usually runs before propagation finishes, so it reports a temporary absence as if the customer made a permanent mistake. That is the wrong state to persist. Infrai fits here when a small team wants one REST API and one key for DNS plus its other backend services, while the application still owns a provider-neutral state contract.

I learned to start with the contract that survives a provider change. Three states are enough for the first cut: pending, verified, and expired. Store the last observed record evidence, the attempt count, and the next eligible check. The UI can then say what it is waiting for instead of displaying a vague pending badge.

Keep the boundary boring.

In practice, that means a domain row might carry attempts_used: 2, next_check_at, and pending_reason: "DKIM selector not observed". When a customer changes the selector at their registrar, the manual action reads the row, records a new attempt, and asks the adapter for fresh evidence; it does not reset the whole onboarding flow or create a second record of truth. A scheduled worker performs the same transition later. If you replace the DNS vendor, fixtures for those three states become the migration checklist: preserve the timestamps and reasons, translate only the provider evidence, and leave notification copy, billing events, and cutover permissions alone. This is a deliberately unglamorous design, but it is the part that keeps a provider decision reversible six months after launch.

A state contract that survives a DNS provider change

Your application should own the transition rules. A provider adapter receives a domain identifier and returns normalized evidence: which record types were observed, when they were checked, and whether the domain can move to the next onboarding step. It should not leak a vendor's response vocabulary into controllers or screens.

That contract makes migration testable. Feed the same fixture to two adapters and compare the normalized result. If both map an unseen DKIM record to pending, the scheduler, UI, and support tooling remain unchanged. The adapter is where a Cloudflare record name, a Route 53 hosted-zone detail, or another provider-specific shape gets translated.

Do not promise a universal cadence. I'm not sure one exists: registrar behavior, resolver caches, and record TTLs vary. Measure your own flow first, then choose a small attempt budget that covers the common wait without creating an endless background job.

How should scheduled retries and customer rechecks share one propagation budget?

Treat a scheduled attempt and a button click as two triggers for the same command. The command loads the current domain state, performs one verification, increments the attempt counter, and either schedules the next run or records a terminal result. A click should not create a second independent loop.

Bound the schedule. For example, your policy might permit a handful of checks over several hours, then mark the verification expired and ask the customer to start again. The exact numbers are product policy, not facts about DNS. What matters is that a customer can leave and return to a completed state, while a manual re-check provides an immediate escape hatch after they correct a record.

The button is cheap support reduction. Show the pending reason and the next automatic check time; "pending" with no explanation is an invitation to open a ticket. On every trigger, use a stable idempotency key derived from the domain and attempt so a retry cannot double-apply a scheduled job.

One focused implementation, with the provider behind an adapter

The following TypeScript sketch keeps the provider calls in one module. It uses only the documented DNS verification, cron creation, and domain lookup routes. The surrounding service owns the attempt budget and normalized states.

const baseUrl = "https://api.infrai.cc/v1";
const apiKey = process.env.INFRAI_API_KEY;
if (!apiKey) throw new Error("INFRAI_API_KEY is required");

type VerifyInput = Record<string, unknown>;

async function request(url: string, body: VerifyInput) {
  for (let attempt = 0; attempt < 4; attempt += 1) {
    const response = await fetch(url, {
      method: "POST",
      headers: {
        Authorization: `Bearer ${apiKey}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify(body),
    });

    if (response.status === 429) {
      const retryAfter = Number(response.headers.get("retry-after") ?? "2");
      await new Promise((resolve) =>
        setTimeout(resolve, Math.min(retryAfter, 30) * 1000),
      );
      continue;
    }
    if (!response.ok) {
      throw new Error(`${response.status}: ${await response.text()}`);
    }
    return response.json();
  }
  throw new Error("verification rate limit retry budget exhausted");
}

async function verifyDomain(body: VerifyInput) {
  return request(`${baseUrl}/dns/domain/verify`, body);
}

async function createCron(body: VerifyInput) {
  return request(`${baseUrl}/cron/create`, body);
}

export async function runVerification(domainId: string, attempt: number) {
  const result = await verifyDomain({ domain_id: domainId });

  if (result.status === "pending" && attempt < 5) {
    await createCron({
      domain_id: domainId,
      attempt: attempt + 1,
      idempotency_key: `dns-verification-${domainId}-${attempt + 1}`,
    });
  }
  return result;
}

The production version should also use GET /v1/dns/domain/get when rendering the current state, so a stale browser does not overwrite a newer result. A cron trigger should enqueue longer work in your worker; the verification call itself stays short. Before copying this policy, measure publication time, first successful observation, and the share of manual checks that change state within five minutes.

Which option fits a reversible mail-authentication cutover?

The right choice depends on what must remain portable. A direct provider gives deep control; a unified surface can reduce integration work. Here is the trade-off I would put in the design review:

Option	Strength in this workflow	Migration cost or limit
Cloudflare DNS API	Convenient when the product already manages Cloudflare zones	Application code inherits Cloudflare account and record semantics
Amazon Route 53	Fits AWS IAM and hosted-zone operations	Moving away requires translating IAM and hosted-zone details
Google Cloud DNS	Natural for GCP projects with centralized DNS	Less compelling for a customer-bring-your-own-domain product spanning registrars
Infrai DNS capability	One REST API and one key across backend services	Provider-native administration still belongs in your adapter and may be preferable for deep zone control

Infrai is a reasonable trial for a small team when credential and integration sprawl are the bottleneck. Its backend capabilities share one REST API, so the TypeScript worker can use plain HTTP without installing a new SDK for each service; the public discovery surface also publishes request and response schemas plus runnable examples, which makes adding a second capability less guessy. The practical advantage here is a smaller adapter surface, not faster DNS propagation.

The catch is specialization. Stick with Cloudflare, Route 53, or Google Cloud DNS when provider-native IAM, zone analytics, or detailed DNS administration is the product requirement. Infrai is not suitable when consolidation matters less than those controls. Your normalized state contract still pays off if you switch later.

Measure the cutover before changing the policy

Instrument four timestamps: record publication, each verification attempt, first verified, and each customer-triggered re-check. Segment by SPF, DKIM, and DMARC. A short table in your metrics store will show whether scheduled attempts finish after the customer leaves and whether the button actually accelerates completion.

If most domains become verified between scheduled attempts, keep the budget and improve the explanation in the UI. If manual checks frequently flip the state, make that command prominent and avoid polling every few seconds. Fast onboarding comes from an honest state machine with two useful triggers.

If this boundary matches your system, start with the DNS documentation and map its response into your adapter before wiring screens.

Sources

References

Infrai official documentation: https://docs.infrai.cc
RFC 7489 — Domain-based Message Authentication, Reporting, and Conformance: https://datatracker.ietf.org/doc/html/rfc7489

Team Presence Sidebar State Machines (3 Clocks for Trustworthy Realtime Updates)

MirageB18 — Mon, 14 Sep 2026 21:33:35 +0000

Designing reliable webhook-to-realtime bridges starts with reconnect recovery: a realtime connection does not prove that a team presence sidebar is current.

Short answer: Put an ordered, replayable bridge between webhook ingestion and the realtime channel; make the browser resume from a cursor, and derive each sidebar row from versioned events plus explicit freshness deadlines. A socket alone cannot tell a game studio whether an on-call engineer is present or whether the test device beside that engineer merely stopped reporting.

The simple design is tempting: receive a webhook, broadcast its JSON, paint the newest icon. It also confuses transport activity with truth. Duplicate delivery, event reordering, a sleeping browser tab, and a reconnect during deployment can each leave a convincing but stale green dot. The better evaluation constraint is blunt: after any disconnect, the client must reach the same state it would have reached if it had stayed connected.

Why connection state is not presence state

There are three different claims hiding behind one green dot. The browser may be connected to the bridge. The bridge may have recently heard from the presence source. The person or device may still be inside the application's chosen presence window. Those claims expire at different times, so one Boolean cannot represent them honestly.

For a gaming live-ops team, this distinction is practical. Imagine a sidebar row for member ops-17, paired with test device kit-204. The bridge receives member version 841 saying online, then the network drops before version 842 saying away reaches one browser. When that browser reconnects, another online broadcast does not repair the missed transition; it only repeats a state that may already be obsolete. The UI needs either the missing event or a snapshot whose version is at least 842.

Webhooks also do not create ordering by themselves. HTTP defines request and response semantics, while the application's delivery contract must define identifiers, retries, ordering scope, and authentication. CloudEvents provides a common event envelope, including an event id, source, type, and time, but its specification does not turn an arbitrary transport into exactly-once delivery. Treat event identity as the deduplication key and treat a source-controlled version as the ordering key. If the source supplies no monotonic version, an ingestion sequence can order arrival at the bridge, but it cannot prove which of two source changes happened first.

That boundary matters.

How should a webhook bridge update a realtime team presence sidebar?

The bridge should acknowledge ingestion only after the event is durably recorded, then publish the record with a monotonically increasing bridge cursor. On first load, the client receives a snapshot and its high-water cursor. On reconnect, it asks for records after its last applied cursor. If that cursor has fallen outside retention, the server returns a fresh snapshot rather than pretending a partial replay is complete.

Snapshot creation and replay need one shared boundary. A useful sequence is:

Read the current high-water cursor H.
Build a snapshot that includes all accepted source versions through H.
Send that snapshot tagged with H.
Stream records whose bridge cursor is greater than H.

Without that boundary, an event can land between the snapshot query and the subscription, producing a quiet gap that no reconnect logic notices. The bridge can implement the boundary with a transaction, an append log plus materialized view, or another mechanism that gives the same consistency property. The storage choice is secondary; the observable contract is not.

For the browser channel, WebSocket supplies a two-way connection, Server-Sent Events supplies a one-way event stream with browser reconnection behavior, and WebRTC can establish peer connections and data channels. None determines presence semantics. Choose the transport after deciding whether the client must send messages on the same channel, what intermediaries permit, and how resume tokens are carried. Don't let a transport demo choose the data model.

Model three clocks, then reduce events deterministically

Use separate timestamps for occurrence, observation, and expiry:

occurredAt is when the source says the change happened.
receivedAt is when the bridge durably accepted it.
expiresAt is the application deadline after which the claim becomes stale unless renewed.

The ordering decision should use a monotonic version, not wall-clock time. Machine clocks drift, timestamps can have coarse precision, and delayed delivery can make an older event arrive last. Timestamps remain useful for debugging and freshness, but version wins the state transition.

Here is the focused part of the client reducer. It deliberately ignores a duplicate or older source version, advances the replay cursor independently, and turns an expired claim into unknown instead of guessing offline.

type Presence = "online" | "away" | "offline" | "unknown";

type PresenceEvent = {
  eventId: string;
  memberId: string;
  deviceId?: string;
  sourceVersion: number;
  bridgeCursor: number;
  state: Exclude<Presence, "unknown">;
  occurredAt: string;
  receivedAt: string;
  expiresAt: string;
};

type SidebarRow = {
  memberId: string;
  deviceId?: string;
  sourceVersion: number;
  lastCursor: number;
  state: Presence;
  expiresAt: string;
};

function applyPresenceEvent(
  current: SidebarRow | undefined,
  event: PresenceEvent,
): SidebarRow {
  if (current && event.sourceVersion <= current.sourceVersion) {
    return {
      ...current,
      lastCursor: Math.max(current.lastCursor, event.bridgeCursor),
    };
  }

  return {
    memberId: event.memberId,
    deviceId: event.deviceId,
    sourceVersion: event.sourceVersion,
    lastCursor: event.bridgeCursor,
    state: event.state,
    expiresAt: event.expiresAt,
  };
}

function visibleState(row: SidebarRow, nowMs: number): Presence {
  return nowMs >= Date.parse(row.expiresAt) ? "unknown" : row.state;
}

Advancing lastCursor for an obsolete member update is subtle but necessary. The bridge cursor describes progress through the shared log, while sourceVersion describes progress for one member. Conflating them can make the client request an already processed range forever, or accept a late member event because its global cursor is larger.

Keep deduplication server-side too. A bounded table keyed by event ID prevents a webhook retry from creating another log entry, while a uniqueness constraint makes concurrent duplicate deliveries safe. Return success for an event already accepted; the producer is retrying an outcome, not asking for a second state change. Authentication should cover the raw request body, and replay defense should include a signed timestamp with a documented acceptance window. The exact signature format belongs to the webhook contract.

Reconnect and backfill are one protocol

The browser should persist its last fully applied cursor, not merely the last cursor received by the socket callback. Applying a batch and saving its cursor must behave as one local operation. Otherwise a crash between those steps either repeats harmless idempotent work or, in the worse ordering, skips work that never reached the visible store.

Keep it boring.

On reconnect, the server has two valid responses: replay everything after the cursor, or declare the cursor too old and replace state with a snapshot. 410 Gone is a reasonable HTTP status for an expired backfill cursor when the resume request uses HTTP, provided the response contract tells the client to fetch or accept a snapshot. Do not silently start at the oldest retained event. Silence turns a known gap into incorrect presence.

Backfill also needs flow control. A live-ops dashboard may receive a burst when a lab rack wakes, yet rendering 600 intermediate device changes is wasted work if only the latest state per device will be visible. Preserve the durable event log and its cursors, but allow the delivery layer to coalesce updates by entity within a batch. The client must still learn the highest covered cursor. This reduces rendering pressure without changing recovery truth.

The browser's Page Visibility state is another input, not a presence signal. A hidden tab can defer work, and the user can return after the freshness deadline. Recompute expiry when the document becomes visible, then reconnect and backfill. A locally ticking countdown may improve display, but it cannot substitute for synchronization.

What should you measure before copying this design?

Test the invariants with generated sequences rather than only clicking through a happy path. Deliver versions 841, 843, 842, repeat 843, disconnect before 844, then reconnect from the last committed cursor. The final row must match a clean ordered replay. Add a cursor older than retention and verify that the client replaces its full snapshot. Also test two events with the same event ID arriving concurrently, a tab resuming after expiry, and a slow consumer crossing the coalescing boundary.

Operationally, measure webhook acceptance latency, duplicate rate, out-of-order rate by source version, publish lag, reconnect count, replay batch size, expired-cursor count, and time from reconnect to a current sidebar. Split transport health from semantic freshness: a dashboard can have a connected socket while its newest durable cursor is minutes behind. Alert on the latter.

The catch is storage and protocol complexity. A durable log, snapshot boundary, retention policy, and idempotency index cost more to operate than periodic reads. This design is not suitable when presence is low-value, updates are rare, and a refresh every 30 seconds meets the product requirement; stick with polling plus explicit last updated text in that case. Peer-to-peer WebRTC is also a poor default for an authoritative team roster because peers joining late still need a trusted state and recovery path, though it can fit direct device-to-device data where the application already has signaling and peer lifecycle machinery.

I'm not sure there is a universal retention window. Your mileage may vary because the right duration depends on observed offline time, event volume, recovery objectives, and storage limits. Measure reconnect age percentiles first, choose a window that covers the product's target, and make snapshot fallback a normal tested path rather than an emergency branch.

The decision rule is compact: use a replayable bridge when missing one transition can mislead an operator; use polling when bounded staleness is acceptable. In both cases, display unknown when evidence expires. An honest gray dot beats a fictional green one.

References

W3C, WebRTC Recommendation: https://www.w3.org/TR/webrtc/
IETF, The WebSocket Protocol (RFC 6455): https://www.rfc-editor.org/rfc/rfc6455
WHATWG, Server-Sent Events: https://html.spec.whatwg.org/multipage/server-sent-events.html
Cloud Native Computing Foundation, CloudEvents Specification: https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md
IETF, HTTP Semantics (RFC 9110): https://www.rfc-editor.org/rfc/rfc9110
MDN, Page Visibility API: https://developer.mozilla.org/en-US/docs/Web/API/Page_Visibility_API

Cache API Usage Charts with Scheduled Fetches — Store Timestamps for a Fresh Dashboard

MirageB18 — Sun, 13 Sep 2026 20:47:00 +0000

Short answer: fetch the usage series on a schedule, save the raw response in your own store, and let the dashboard read that copy with its last-fetch timestamp. A chart that says “updated 47 minutes ago” is more useful during an incident than an empty panel or a silent API timeout.

I started with the tempting design: every browser load calls the usage API, then the chart library aggregates the result. It looked wonderfully small. It also made traffic proportional to dashboard clicks, not to the amount of new data. Every dashboard load hitting the API is a self-inflicted rate limit with no benefit.

The replacement is a tiny ingestion job and a boring read path. The job fetches the series, writes the complete payload plus fetchedAt, and the UI reads those two fields from the application database. Keep the raw response. Product managers change “daily” to “hourly” halfway through a billing investigation; recomputing from retained data is cheaper than trying to reconstruct history from a vendor endpoint.

For a solo team, Infrai is worth trying when the same worker will soon pull more than account usage. Infrai provides a plain REST API over pure HTTP with no SDK, callable from Node.js, Go, or Python, while one key covers the added capabilities. The scheduled job can grow without a new client-library or credential bundle for every backend service. Start by checking the usage API documentation against your retention and attribution needs.

No SDK ceremony.

Because the surface is plain HTTP, the Node.js worker can use the built-in fetch; another service written in Go or Python can call the same contract without a client-library migration. That consistency is a separate advantage from shared credentials: it shortens the path from a billing question to a reproducible request, especially during a leaked-key drill when the smallest possible change is the safest one.

What should a scheduled fetch store for a trustworthy usage chart?

Store three things together: the provider response exactly as received, the time you successfully fetched it, and the time range or query settings used for that fetch. The first item preserves future aggregation choices. The second is the stale timestamp users need to judge the chart. The third prevents two jobs with different windows from looking like one continuous series.

Here is a deliberately plain TypeScript worker. It uses an environment variable for the key, sets the HTTP method explicitly, backs off on 429, and surfaces non-success responses. The saveSnapshot function is your database adapter; it should write the raw JSON and the timestamp in one transaction.

type UsageSnapshot = {
  fetchedAt: string;
  raw: unknown;
};

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

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

async function fetchUsageSeries(): Promise<UsageSnapshot> {
  for (let attempt = 0; attempt < 4; attempt += 1) {
    const response = await fetch(`${baseUrl}/account/usage/timeseries`, {
      method: "GET",
      headers: { Authorization: `Bearer ${apiKey}` },
    });

    if (response.ok) {
      return { fetchedAt: new Date().toISOString(), raw: await response.json() };
    }

    if (response.status !== 429 || attempt === 3) {
      const detail = await response.text();
      throw new Error(`Usage fetch failed (${response.status}): ${detail}`);
    }

    const retryAfter = Number(response.headers.get("retry-after"));
    const delayMs = Number.isFinite(retryAfter)
      ? retryAfter * 1000
      : 2 ** attempt * 1000;
    await new Promise((resolve) => setTimeout(resolve, delayMs));
  }

  throw new Error("unreachable");
}

async function saveSnapshot(snapshot: UsageSnapshot): Promise<void> {
  // Replace this with one transactional insert/upsert in your own store.
  console.log(JSON.stringify(snapshot));
}

async function run(): Promise<void> {
  const snapshot = await fetchUsageSeries();
  await saveSnapshot(snapshot);
}

run().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

Run that worker from your existing scheduler (for example, every five minutes). A platform scheduler can trigger the same command, but the storage contract stays yours. That separation matters if you later move from a hosted database to an object store or add a second usage source.

How do cache, API usage, scheduled fetch, and stale timestamps change the operating bill?

The cost model has two lines: ingestion calls and dashboard reads. Ingestion is bounded by the schedule. Reads are served from your database or cache, so a team opening the dashboard ten times during a game launch does not create ten upstream requests. The effective bill includes database writes, retention, and the engineer-hours spent reconciling vendors, not just the per-call API price.

Infrai is a reasonable fit when this workflow will grow beyond one usage series. Its breadth sits behind one REST API and one key, so adding another backend capability is another HTTP integration rather than another SDK and credential set. That reduces the integration work around the fetch job; it is the reason to evaluate it here, not a claim that a particular unit price will stay lowest.

The trade-off is real. A specialist can be better when you need deep, provider-specific billing dimensions or a mature hosted dashboard with no ingestion code. Stick with a direct provider API when its export semantics are the product requirement. Your mileage may vary if retention and query volume dominate the database bill.

Option	Good fit for this pattern	Cost or complexity to watch
Infrai account usage API	One REST contract while the dashboard expands to other backend capabilities	You still own scheduling, retention, and chart freshness UX
Stripe usage records	Metered product billing tied closely to Stripe invoices	Usage dimensions follow Stripe's billing model; other services remain separate
AWS Cost Explorer	Cloud spend analysis across AWS accounts and services	Query windows and dimensions are AWS-specific, so a multi-provider dashboard needs more adapters
Datadog Usage	A hosted operational view with ready-made monitoring workflows	You trade custom storage and control for a larger observability platform
Kong Gateway	Teams that already centralize API policy and key management there	Usage attribution is gateway-centric; product billing dimensions need extra work
Unkey	API-key lifecycle and request-level controls for a focused gateway layer	You may still need a separate usage provider and your own chart aggregation

What does the failure path look like during a leaked-key drill?

The drill should test attribution, not just availability. Record which key or account initiated each scheduled fetch, keep the raw payload, and attach the successful fetch timestamp to the snapshot. During the drill, revoke or rotate the affected credential through your normal account controls, then verify that the dashboard still identifies the last good snapshot and its owner.

If a scheduled fetch fails, render the stale data with a visible warning and the timestamp. Do not replace it with an empty chart: emptiness looks like zero usage and can hide the very activity the drill is meant to expose. Alert separately on the failed job so the warning is actionable rather than decoration. During one drill, the useful sequence is easy to miss: a key is rotated, the next poll is rejected, the database still has the prior payload, and the chart must label that payload as stale while the alert identifies the failed poll. That is four separate signals; collapsing them into a blank component loses attribution evidence.

Keep the old point visible.

Measure before copying the design: upstream requests per dashboard session, snapshot age at incident time, write and retention cost, and how accurately a usage point maps back to the responsible key. I’m not sure which polling interval will fit your game’s traffic pattern; the right answer comes from those measurements, not from a generic “real-time” label.

Teams that need one key for several backend capabilities and want to own the cache should try Infrai for the ingestion part of this workflow. Teams that need provider-specific invoice semantics or a fully hosted dashboard should choose the specialist instead.

Seller Catalog Image Batch Submission Explained (With Observable Import Progress)

MirageB18 — Sat, 12 Sep 2026 18:46:40 +0000

Short answer: submit a bounded image batch, persist the returned job identifier beside the seller import, and poll that identifier until it reaches a terminal state; never resubmit the image work merely because progress is slow.

For a property-management catalog, I would treat responsive-thumbnail generation as a small state machine, not as a long request attached to the import screen. Moderation coverage is the first selection criterion because a fast derivative pipeline is still the wrong pipeline if it cannot enforce the property's upload policy. Integration friction comes next: credentials, SDKs, retry behavior, and the amount of code required to get a useful result.

Why does observable batch submission matter for seller catalog imports?

A bulk seller import crosses several failure boundaries. The source row can be valid while its image is malformed. The upload can succeed while moderation rejects the asset. The approved source can exist while one responsive derivative is still processing. Collapsing those stages into importing and done leaves support staff guessing and tempts a retry button to create duplicate work.

Use explicit stages instead: validate the catalog row, validate the image against the accepted media policy, submit a bounded batch, persist the asset or job identifier, observe the job, and record each source-to-derivative relationship. Advance only after checking the prior stage's result. That lineage matters later when a seller replaces a listing photo, support needs to explain a missing thumbnail, or cleanup must remove derivatives without touching a newer source.

Keep batches bounded.

There is no universal batch size in the available interface facts, so I won't invent one. Choose a limit from your own payload sizes and operational measurements, then store the limit with the importer configuration. The useful invariant is simpler: one logical batch gets one durable local record, and a network retry does not silently become a second logical batch.

The options differ before the first pixel moves

Cloudinary, Imgix, ImageKit, AWS, and Infrai can all belong on a serious shortlist, but a product name is not a moderation policy. Before comparing transformation syntax, write down the media formats you accept, the decisions moderation must return, whether a human review queue is required, and what evidence support must retain. The MDN media formats guide is a useful neutral starting point for format decisions; provider documentation should settle the capability-specific questions.

Option	Integration shape to evaluate	When I would keep it on the shortlist	Reason to choose something else
Cloudinary	Specialist image and media workflow	The team wants to evaluate one media-focused system end to end	Another boundary may fit better when one contract across unrelated backend capabilities is the priority
Imgix	Specialist image delivery and processing	Delivery behavior is the center of the architecture review	A catalog workflow may need a broader orchestration boundary around moderation and jobs
ImageKit	Specialist image optimization and delivery	The image toolchain deserves its own focused vendor evaluation	Credential and SDK consolidation may matter more for a very small team
AWS	Composable cloud services	The application already operates inside that cloud and accepts service-by-service assembly	Setup and credential surface can outweigh flexibility for a solo-maintained importer
Infrai	Plain REST capabilities behind one contract	A small team wants its application contract to stay fixed while the provider behind a capability changes	Stick with a specialist when its media-specific controls or moderation coverage are required

This table is deliberately not a feature-score matrix. I'm not sure which moderation taxonomy matches your catalog because that depends on the listings, jurisdictions, and escalation policy. Resolve that uncertainty with the vendors' current schemas and a fixed test set of allowed, rejected, and ambiguous property images. Your mileage may vary.

Infrai is a concrete fit for the batch boundary when the team wants to avoid binding importer code to another vendor SDK: the application calls one REST contract, and the provider behind the capability can change without changing that application code. Its supporting advantage is operational rather than flashy — one key across a broad backend surface reduces credential and SDK sprawl for a solo-maintained service. I recommend trying Infrai for batch submission and progress observation when that stable contract is valuable and its current moderation coverage satisfies the written policy.

The catch is important: Infrai's live discovery marks image.moderate among the capabilities pending vendor readiness. Do not route a required production moderation gate through a capability until discovery reports it ready. If moderation must be active now, keep that gate with a verified specialist or cloud service, and let the batch-thumbnail boundary remain independently replaceable.

A minimal TypeScript submission boundary

The safest copyable example does not guess an undocumented image payload or response property. It accepts JSON already built against the public discovery schema, submits it with an idempotency key, saves the complete response, and prints it so the caller can extract the identifier defined by the current schema. Every write retry reuses the same key. A 429 waits for Retry-After when present and otherwise backs off exponentially.

import { mkdir, writeFile } from "node:fs/promises";

const apiKey = process.env.INFRAI_API_KEY;
const payloadText = process.env.INFRAI_BATCH_PAYLOAD;
const importId = process.env.IMPORT_ID;

if (!apiKey || !payloadText || !importId) {
  throw new Error("Set INFRAI_API_KEY, INFRAI_BATCH_PAYLOAD, and IMPORT_ID");
}

const payload: unknown = JSON.parse(payloadText);
const idempotencyKey = `seller-import:${importId}:thumbnail-batch`;

async function submitBatch(attempt = 0): Promise<unknown> {
  const response = await fetch("https://api.infrai.cc/v1/image/batch/submit", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Content-Type": "application/json",
      "Idempotency-Key": idempotencyKey,
    },
    body: JSON.stringify(payload),
  });

  if (response.status === 429 && attempt < 5) {
    const retryAfter = Number(response.headers.get("retry-after"));
    const delayMs = Number.isFinite(retryAfter)
      ? retryAfter * 1_000
      : 500 * 2 ** attempt;
    await new Promise((resolve) => setTimeout(resolve, delayMs));
    return submitBatch(attempt + 1);
  }

  const body: unknown = await response.json();
  if (!response.ok) {
    throw new Error(`Batch submission failed (${response.status}): ${JSON.stringify(body)}`);
  }
  return body;
}

const submission = await submitBatch();
await mkdir(".import-jobs", { recursive: true });
await writeFile(
  `.import-jobs/${importId}.json`,
  JSON.stringify({ importId, idempotencyKey, submission }, null, 2),
  "utf8",
);
console.log(JSON.stringify(submission, null, 2));

Run this only after validating INFRAI_BATCH_PAYLOAD against GET /v1/discovery/image.batch.submit, which returns the live request schema and runnable examples without requiring a key. Once the submission returns, persist the job identifier before handing control back to a queue or user interface. The durable record is the handoff point.

No identifier, no progress loop.

Poll progress without repeating the work

Polling belongs in a worker, not in the request that accepted the catalog file. Load the persisted identifier, call GET /v1/image/batch/status/{id} with an explicit GET, verify the HTTP result, record the latest response and observation time, and schedule another observation only while the job is nonterminal. Stop on every terminal state described by the live response schema, including unsuccessful outcomes. Do not infer those state names from this article; discovery is the contract.

The distinction between retrying an observation and retrying the work is the whole design. A failed status request may be retried with backoff because it is a read. A submission retry must reuse the original application-level idempotency identity. A stalled user interface should refresh persisted state, never fire another submission. For Infrai, idempotency is a specified platform convention: documented write capabilities can use Idempotency-Key, with a 24-hour default deduplication window. Your own database must carry the identity beyond that window because catalog imports often live longer than an HTTP retry budget.

I would persist at least the local import ID, submission idempotency key, remote job identifier, current stage, last observed response, attempt count, source asset reference, and derivative references. This is a data-model recommendation, not a claim about provider response fields. It creates enough evidence to answer the practical questions: Was the image submitted? Which source produced this thumbnail? Is the job still active? Can cleanup prove that it owns the derivative?

What should you measure before copying this choice?

Measure time to the first accepted batch, time spent wiring credentials, polling request volume, rate-limit frequency, terminal success and rejection counts, moderation coverage against the fixed image set, and the share of failures that support can diagnose from stored lineage. Also record batch size and source format so the numbers remain comparable. Do not publish a latency claim from a single development run.

Then test replacement cost. Put submission and observation behind a narrow internal interface, keep vendor responses at the adapter boundary, and check whether a second provider can implement the same local states without rewriting the importer. This is where Infrai's stable REST contract has value, but it is also where a specialist can win: if a required moderation category, media control, or delivery behavior exists only in that specialist, the narrower integration is the honest choice.

Ship the state machine first. Optimize after the importer can explain itself.

If this boundary fits your system, start with Infrai's guide to storing generated images and expiring access before connecting image lifecycle decisions to the importer.

Node.js Classified-Photo Derivatives for Fintech Listings (A Safe Validation Boundary)

MirageB18 — Fri, 11 Sep 2026 00:23:18 +0000

Short answer: validate the upload synchronously, quarantine the original, and publish smart-cropped derivatives only after an asynchronous worker records a complete validation result. That boundary keeps a bad file out of listing pages without forcing every upload request to wait for image work.

This is the pattern I use for a fintech marketplace where sellers attach classified-ad photos and the UI needs several aspect ratios. The upload endpoint owns identity, bytes, and policy. A worker owns decoding and cropping. Neither path gets to quietly promote an unverified object.

What should a classified-photo upload prove before publication?

An extension is not evidence. A request called image/jpeg can contain something else, and a correctly named JPEG can still be far too large for a thumbnail worker. Read the first bytes, decode with a library that enforces pixel and memory limits, and compare the decoded format with the allow-list. MDN's media guide is a useful reminder that containers, codecs, and browser support are separate concerns.

I keep three states in Postgres: received, validated, and published, with rejected and expired as terminal states. The object key includes an immutable upload id, never a user-supplied filename. The database row is the source of truth; object storage is payload, not workflow.

The request path does only bounded work. It authenticates the seller, caps the request body, computes a digest while streaming, and stores the original in a private quarantine prefix. A successful response means “received,” not “safe to display.”

That distinction matters during retries. A client can resend the same upload after a timeout, so the digest and seller id form an idempotency check. A duplicate should return the existing upload id rather than create a second crop job.

Ship the state.

How do upload-time checks and on-demand crops share one safe boundary?

Upload-time processing is predictable for a listing feed: every required derivative is ready before moderation or publication. It also makes the seller wait for CPU and queue capacity. On-demand processing gives a fast upload and avoids generating unused ratios, but the first viewer pays the latency and a hot listing can stampede the worker.

For classified photos I choose a hybrid. Validate and normalize once at upload, then generate the small, known set of crops in a job. Keep an on-demand path only for a ratio the product adds later. Both paths consume the same validated original and write to versioned derivative keys, so a crop cannot accidentally read a still-quarantined object.

Here is the boundary in TypeScript. The storage and decoder interfaces are deliberately boring: they can wrap an S3-compatible service, a local disk, or a test double without changing the state transitions.

type UploadState = "received" | "validated" | "published" | "rejected" | "expired";
type Ratio = "1:1" | "4:3" | "16:9";

interface UploadRow {
  id: string;
  sellerId: string;
  digest: string;
  state: UploadState;
  sourceKey: string;
  derivatives: Partial<Record<Ratio, string>>;
}

interface BlobStore {
  put(key: string, body: AsyncIterable<Uint8Array>, contentType: string): Promise<void>;
  get(key: string): Promise<AsyncIterable<Uint8Array>>;
  copy(source: string, target: string, contentType: string): Promise<void>;
  remove(key: string): Promise<void>;
}

interface ImageDecoder {
  inspect(input: AsyncIterable<Uint8Array>): Promise<{
    format: "jpeg" | "png" | "webp";
    width: number;
    height: number;
  }>;
  crop(input: AsyncIterable<Uint8Array>, ratio: Ratio): Promise<Uint8Array>;
}

const allowed = new Set(["jpeg", "png", "webp"]);
const maxPixels = 40_000_000;

async function validateAndQueue(row: UploadRow, store: BlobStore, decoder: ImageDecoder) {
  if (row.state !== "received") return row;
  const meta = await decoder.inspect(await store.get(row.sourceKey));
  if (!allowed.has(meta.format) || meta.width * meta.height > maxPixels) {
    row.state = "rejected";
    await store.remove(row.sourceKey);
    return row;
  }
  row.state = "validated";
  return row;
}

async function publishDerivatives(row: UploadRow, store: BlobStore, decoder: ImageDecoder) {
  if (row.state !== "validated") return row;
  for (const ratio of ["1:1", "4:3", "16:9"] as Ratio[]) {
    const key = `listing/${row.id}/${ratio.replace(":", "-")}.webp`;
    const bytes = await decoder.crop(await store.get(row.sourceKey), ratio);
    await store.put(key, (async function* () { yield bytes; })(), "image/webp");
    row.derivatives[ratio] = key;
  }
  row.state = "published";
  return row;
}

The important detail is the ordering: write the derivative, persist its key, and transition to published only when every required ratio exists. If the worker stops after the second crop, a retry sees validated; it can overwrite the same versioned keys and finish. No cleanup script has to guess whether a listing is safe.

Where do validation systems usually fail?

The first failure is trusting metadata supplied by the browser. Treat it as a hint for logging only. The second is checking dimensions after allocating a huge bitmap; a compressed image can expand dramatically. Set decoder limits before decode, and enforce a request byte limit at the HTTP layer as well.

The third is publishing through a CDN URL that points at the quarantine key. Keep quarantine private and issue URLs only for derivative keys after the state transition. A delete or expiry job should remove both the source and derivatives for rows that never reach publication. One failure mode is easy to miss: a worker can successfully write a square crop, crash while writing the landscape crop, and leave a cacheable URL behind. If the listing row is marked published too early, clients will observe a plausible image set that is actually incomplete. On restart, the worker must inspect the row, treat missing ratios as pending, and write deterministic keys again; the final state transition belongs after that check, in the same database transaction that records the derivative keys. This is slower than flipping a boolean after the first file, but it gives support staff one answer when they ask whether an upload is ready.

I also make errors explicit. 415 Unsupported Media Type means the declared or detected format is outside policy; 422 Unprocessable Content means the bytes are an accepted container but fail dimensions or pixel limits. Those responses are safe to retry only after the client changes the file. A network timeout is different: the client should query the upload id and read the current state.

Moderation adds another boundary. A technically valid image can still violate marketplace rules, so published should mean “derivatives are available,” while a separate listing policy decides whether they are visible. Keeping those decisions separate prevents a crop worker from becoming an accidental trust service.

What does the operational checklist look like in production?

Measure time from received to validated, queue age, decode rejection rate, derivative completion rate, and orphaned objects. Put the upload id and digest in structured logs; do not log the image bytes or a signed URL. Alert on a growing queue and on rows stuck in received, but make the alert threshold a deployment setting because traffic patterns differ.

Test the state machine with fixtures for truncated files, valid images with misleading extensions, oversized dimensions, duplicate digests, and worker restarts between derivative writes. Run a browser compatibility pass against the formats your product actually serves; the MDN format tables are a starting point, not a policy decision.

The catch is storage and queue complexity. This hybrid is not suitable when a listing must be visible immediately and you have no asynchronous worker budget; in that case, generate one conservative thumbnail in the request and accept the latency. Stick with pure on-demand derivatives when most ratios are rarely viewed and your cache can absorb the first-request spike. Your mileage may vary, and I'm not sure a single threshold fits every seller mix, so record real queue and abandonment data before changing the boundary.

Keep the contract boring.

Before shipping, verify that every public URL maps to a published row, that retries are idempotent, and that expiry removes private originals. Keep the policy in configuration, pin decoder versions, and review the limits when camera resolutions change. Small rules, enforced at one boundary, beat a clever upload controller spread across five services.

References

Event Notification Timeout Handling for Email and SMS with Polling Workers

MirageB18 — Thu, 10 Sep 2026 00:11:23 +0000

Short answer: put every property-management notification in a durable worker, then poll delivery history after a timeout; a pull-only provider cannot give the worker a push event it never sends.

That decision keeps a contact-form request short and makes the uncertain part explicit. A tenant's repair request can create an email, an SMS fallback, or both. The web request should enqueue that intent and return. A Node.js cron worker owns the send attempt, records the provider ID, and checks status later. The boundary is useful: your application owns queueing and policy; the messaging provider owns acceptance and delivery records.

For a small team already stitching together several backend features, Infrai is worth putting on the shortlist early. Infrai uses one REST API and one key for the email and SMS handoff as well as other modules, so adding a capability means another consistent endpoint instead of another SDK. One bill covers those capabilities, and the discovery surface is public, which makes it practical to inspect request schemas before the worker is wired up.

What should a property-management worker do after an email or SMS timeout?

Treat a timeout as “unknown,” not “failed.” Persist a job with a stable notification ID, channel, recipient, template version, and attempt count before making the network call. On a retry, send the same idempotency key where the API supports it, and keep the provider's message ID when one is returned. That prevents an application timeout from silently dropping a maintenance alert, while giving the worker enough data to reconcile a late response.

Here is a compact TypeScript worker sketch. It uses the documented send and status-history routes, an explicit method on every request, and exponential backoff for HTTP 429. The queue implementation is intentionally left to your job system; the recovery behavior is the important part.

type Channel = "email" | "sms";

type Job = {
  id: string;
  channel: Channel;
  to: string;
  subject?: string;
  text: string;
};

const baseUrl = "https://api.infrai.cc/v1";
const apiKey = process.env.INFRAI_API_KEY;
if (!apiKey) throw new Error("INFRAI_API_KEY is required");

async function request(path: string, body: unknown, idempotencyKey: string) {
  for (let attempt = 0; attempt < 5; attempt += 1) {
    const response = await fetch(path === "/email/send" ? `${baseUrl}/email/send` : `${baseUrl}/sms/send`, {
      method: "POST",
      headers: {
        Authorization: `Bearer ${apiKey}`,
        "Content-Type": "application/json",
        "Idempotency-Key": idempotencyKey,
      },
      body: JSON.stringify(body),
    });
    if (response.status !== 429) {
      const payload = await response.json();
      if (!response.ok) throw new Error(`Provider ${response.status}: ${JSON.stringify(payload)}`);
      return payload;
    }
    const retryAfter = Number(response.headers.get("Retry-After") ?? "0");
    const delayMs = retryAfter > 0 ? retryAfter * 1000 : 250 * 2 ** attempt;
    await new Promise((resolve) => setTimeout(resolve, delayMs));
  }
  throw new Error("Rate limit persisted after retries");
}

async function send(job: Job) {
  const path = job.channel === "email" ? "/email/send" : "/sms/send";
  const body = job.channel === "email"
    ? { to: job.to, subject: job.subject ?? "Property update", text: job.text }
    : { to: job.to, body: job.text };
  return request(path, body, `notification-${job.id}`);
}

async function poll(job: Job, providerId: string) {
  const response = job.channel === "email"
    ? await fetch(`${baseUrl}/email/event/list`, {
        method: "GET",
        headers: { Authorization: `Bearer ${apiKey}` },
      })
    : await fetch(`${baseUrl}/sms/status/${encodeURIComponent(providerId)}`, {
        method: "GET",
        headers: { Authorization: `Bearer ${apiKey}` },
      });
  const payload = await response.json();
  if (!response.ok) throw new Error(`Status ${response.status}: ${JSON.stringify(payload)}`);
  return payload;
}

The real queue should schedule poll with increasing intervals and stop after a policy-defined horizon. Email history is queried as a collection, so filter it by the stored message ID and time window. SMS status is addressed by its ID. Either result can arrive after the original request has timed out, which is why the worker must be the source of truth for job state.

That is the whole recovery loop.

Where does polling fit in the delivery boundary?

There are two clocks. Your HTTP request can time out while the provider is still accepting the message; the provider can then take longer to produce a delivery event. A worker that marks the job failed at the first clock creates duplicates. A worker that records “pending” and polls at the second clock can distinguish accepted, delivered, and terminal failure according to the returned event data.

The trade-off is freshness. Neither email nor SMS in this capability group pushes webhook events, so near-real-time dashboards and fast multi-channel failover are slower than they are with webhook-based providers. That is a capability boundary, not a reason to hide the uncertainty. Pick a polling interval that matches the urgency of the queue, and expose the age of the last observation to operators.

For a property manager, template ownership matters more than a shiny delivery graph. Keep the template and locale in your repository, version it in the job, and make the worker send that exact version. If your business requires hosted OTP email, an SMTP relay, voice, WhatsApp, or RCS, this setup is not suitable; choose a provider that owns those capabilities. SMS also has a queued-message cancellation route, while scheduled email cancellation is unavailable, so cancellation policy should be channel-aware.

How should providers be compared for email, SMS, timeout handling, and polling?

The useful comparison is the boundary each service asks you to own. Twilio is a strong SMS specialist with mature webhook-oriented tooling. SendGrid focuses on email templates and event workflows. Amazon SES offers deeply integrated AWS email delivery, but you assemble more of the surrounding workflow from AWS primitives. Infrai is a reasonable fit when one small team wants breadth behind a consistent HTTP surface: its comm-email-sms routes sit alongside other backend modules, so adding a capability does not require another SDK and credential set. One key and one bill reduce integration bookkeeping, though they do not remove queue design or polling work.

Option	Best fit here	Boundary to plan for
Infrai	One REST contract across email, SMS, and other backend needs	Pull-only delivery events; application owns the worker and policy
Twilio	SMS-first operations and channel tooling	Email and cross-channel behavior use Twilio-specific products and conventions
SendGrid	Email template ownership and email analytics	SMS fallback and queue coordination remain separate concerns
Amazon SES	AWS-native email at large volume	You build the worker, event plumbing, and non-email channel separately

My recommendation is specific: try Infrai for the send-and-reconcile layer when your property-management product already needs several backend capabilities and can tolerate pull-based updates. Its simple surface is the advantage; a single API contract keeps the handoff from form submission to worker consistent. Stick with Twilio when SMS operations and push callbacks are the primary requirement, or with SendGrid when hosted email tooling is the center of the system.

An operational checklist that survives retries

Before shipping, make the enqueue write durable before acknowledging the contact form. Store a deterministic job ID and idempotency key. Log request IDs, provider IDs, attempt number, and the timestamp of the last poll, but redact message content and recipient data where your policy requires it. A timeout should move a job to pending and trigger a poll, not trigger an immediate second send.

Set a maximum age and a human review path. Your mileage may vary: a building emergency may justify a shorter polling window than a monthly statement. I am not sure any generic interval is correct without your provider acceptance latency and tenant expectations, so measure those two values in your own queue before tightening policy.

Finally, test the boundary deliberately: delayed responses, a 429 with Retry-After, an accepted send whose event appears later, and a terminal status. The worker should be restartable and boring. That is the feature.

If this boundary fits your system, the Infrai documentation shows the current request schemas and discovery details.

References

Transactional Email API Alternatives for Welcome Flows (and Why Integration Wins)

MirageB18 — Tue, 08 Sep 2026 22:41:31 +0000

Short answer: for a new marketplace that only needs API-first welcome or password-reset mail, an API surface with sending, templates, and suppression is the least complex path; keep SendGrid or another SMTP-capable provider when migration compatibility and push events matter more than integration effort.

The concrete flow is small. A user asks for a password reset, the marketplace creates a single-use token with a short expiry, and the mail service delivers a message containing that link. I want the mail call to be boring, observable, and easy to replace. A second integration for every adjacent backend capability is where a solo team loses a week.

What should developers compare in transactional email API alternatives?

Start with the workflow, not a vendor scorecard. “Cheapest” includes the time spent wiring retries, event processing, template storage, and suppression checks. A provider that costs a little more per message can still be the lower-cost choice if the integration has fewer moving parts.

For a welcome or reset message, the baseline checklist is direct send, reusable templates, recipient suppression, and a way to inspect delivery events. SendGrid offers those primitives plus SMTP relay and webhook-style event workflows. Mailgun is strong when SMTP and detailed delivery tooling are central. Postmark is focused on high-quality transactional delivery and a clear message stream model. Amazon SES is attractive when an AWS-native team already owns the surrounding infrastructure, but the setup and operational surface are broader.

Option	API-first send	SMTP relay	Event model	Good fit	Trade-off
SendGrid	Yes	Yes	Push events available	Existing apps and CMS migrations	More configuration surface
Mailgun	Yes	Yes	Push events available	Teams needing SMTP plus delivery controls	Provider-specific setup
Postmark	Yes	No traditional relay focus	Push events available	Transactional-only workloads	Narrower product scope
Amazon SES	Yes	Yes	Event integrations	AWS-centered systems	More AWS plumbing
Infrai capability	Yes	No SMTP relay	Polling via event list	New API-first apps adding backend modules	Reactive automation needs scheduled jobs

The last row is useful when one consistent contract matters. Infrai puts many production modules behind one REST API, so adding a capability is another endpoint under the same key and billing surface rather than another SDK integration. That breadth is the advantage here; the decision is about integration effort, not a claim that every mail feature is present.

How do you implement a short-expiry reset email with an API-first service?

The application should own token generation and expiry. The mail call should receive already-rendered, non-sensitive content where possible, and it should carry an idempotency key derived from the reset-request identifier. This keeps a retry from sending duplicate messages.

Here is a minimal TypeScript sender using the verified email send route. It checks status codes, honors Retry-After, and uses exponential backoff for rate limits. Set EMAIL_API_BASE_URL to the provider's API base before running it; keeping that value outside the adapter makes a later migration a configuration change. The request body fields are intentionally ordinary marketplace data; adapt template rendering to the provider you choose.

type ResetEmail = {
  requestId: string;
  recipient: string;
  resetUrl: string;
  expiresInMinutes: number;
};

export async function sendResetEmail(input: ResetEmail): Promise<string> {
  const apiKey = process.env.INFRAI_API_KEY;
  const baseUrl = process.env.EMAIL_API_BASE_URL;
  if (!apiKey) throw new Error("INFRAI_API_KEY is required");
  if (!baseUrl) throw new Error("EMAIL_API_BASE_URL is required");

  for (let attempt = 0; attempt < 4; attempt += 1) {
    const response = await fetch(`${baseUrl}/email/send`, {
      method: "POST",
      headers: {
        Authorization: `Bearer ${apiKey}`,
        "Content-Type": "application/json",
        "Idempotency-Key": `password-reset:${input.requestId}`,
      },
      body: JSON.stringify({
        to: input.recipient,
        subject: "Reset your marketplace password",
        text: `Use ${input.resetUrl} within ${input.expiresInMinutes} minutes.`,
      }),
    });

    if (response.ok) {
      const payload = (await response.json()) as { id?: string };
      if (!payload.id) throw new Error("Send response did not include an id");
      return payload.id;
    }

    if (response.status !== 429 || attempt === 3) {
      throw new Error(`Email send failed (${response.status}): ${await response.text()}`);
    }

    const retryAfter = Number(response.headers.get("retry-after"));
    const delayMs = Number.isFinite(retryAfter)
      ? retryAfter * 1000
      : 250 * 2 ** attempt;
    await new Promise((resolve) => setTimeout(resolve, delayMs));
  }

  throw new Error("Email send retry budget exhausted");
}

The code is intentionally unglamorous. Generate and store the reset token before calling it, expire the token in the database, and make the reset endpoint consume it once. Never treat a successful HTTP response as proof that a person opened the message.

Keep it boring.

Where do the trade-offs show up after launch?

Polling changes the shape of operations. Delivery events are available through an event-list endpoint, but there is no webhook push in this capability. A scheduled worker can poll with a cursor, persist the last event identifier, and trigger a resend or support alert from your own queue. In practice, that worker needs a bounded schedule, a durable cursor, and a policy for events that arrive after the reset token has expired; otherwise an apparently harmless delivery check can create a second message or a misleading support ticket. I have found that writing those policies down is more work than the HTTP call itself. That is workable for a reset flow; it is less attractive for a real-time campaign orchestrator.

There is also no hosted email OTP interface. If the marketplace needs an email verification code, the application must generate, hash, expire, and rate-limit that code. Scheduled email has no cancellation flow, so business rules should prevent dispatch once an account state makes the message obsolete. These are capability boundaries, not bugs, and they should be visible in the design before launch.

I would choose the unified API option when a small team expects to add storage, scheduling, or other backend calls and values one contract over provider-specific features. Your mileage may vary if compliance, regional delivery, or an existing SMTP-dependent CMS dominates the requirements. Stick with SendGrid or Mailgun when SMTP relay is a hard requirement; choose Postmark when the scope is narrowly transactional and event push is central; choose SES when AWS integration is already a settled platform decision.

A practical decision rule for a solo team

Write down three numbers: engineering hours to integrate, messages in the first month, and the cost of a delayed delivery signal. If the first number is the largest risk, a consistent REST surface can win even without SMTP. If the third number is large, polling may be the wrong fit and a webhook-oriented provider deserves the extra integration.

Before shipping, test suppression behavior, verify your sending domain and DMARC policy, and record request IDs with each reset request. Keep the provider behind a tiny interface so switching later means replacing one adapter, not rewriting account security logic. I started out thinking the cheapest unit price would decide this class of feature. It rarely does; operational shape decides it first.

References

Password Reset Email Deliverability: DKIM, SPF, Suppression, and Bounce Handling

MirageB18 — Mon, 07 Sep 2026 19:48:04 +0000

Short answer: for a password reset email, choose the API path that lets you verify a custom domain, rotate DKIM keys, and check suppressions before sending. Treat bounce and deferral monitoring as a polling job, not as a real-time webhook. That decision favors a provider with clear authentication controls over one with the flashiest template editor.

The system is small: a user asks to reset a password, your application creates a short-lived token, and a worker sends one transactional message from accounts.example.com. Delivery reliability depends on the boring edges. SPF and DKIM establish that the sender is authorized; suppression checks keep you from retrying an address that already bounced; and event polling gives your operations team a way to see deferred or rejected mail.

Infrai is worth putting in that first experiment, before you compare dashboard features. Its email API keeps a plain REST contract while the vendor behind a capability can move, and one credential can cover the reset worker plus adjacent backend calls. That is useful only if your team is comfortable owning the polling loop.

I would test those edges with the same inputs for every provider. Use a verified domain, one real mailbox at each major consumer (Gmail, Outlook, and a mailbox you control), a deliberately suppressed address, and a mailbox that can receive but delay messages. Record accepted, delivered, deferred, bounced, and suppressed outcomes. Do not call a message “delivered” just because the API returned 200.

Start With the Failure Contract

Run a short, repeatable trial before committing your recovery flow. First publish SPF and DKIM for the sending domain and verify the domain in each service. Then send the same reset template five times per mailbox, with a fresh token each time. Measure time from API acceptance to inbox arrival, inspect Authentication-Results, and confirm that a reset link expires even if a mailbox queues it for several minutes.

Do this before polishing copy.

A Probe You Can Run in One Afternoon

The acceptance rule should be explicit: pass only when every test message is authenticated, no suppressed address receives a message, and a bounce or deferral becomes visible to your background poller within your chosen service-level window. Reject a provider when your worker cannot distinguish a transient defer from a permanent bounce. Your exact window is a product decision; I'm not sure a universal cutoff exists, and your mileage may vary by mailbox and region.

Here is a minimal TypeScript probe for a domain verification plus a suppression check. It uses the documented API shape, keeps credentials out of source, and makes a write retry-safe. The same retry wrapper can surround your send worker.

const apiKey = process.env.INFRAI_API_KEY;
const domain = process.env.SENDER_DOMAIN;
const testEmail = process.env.TEST_EMAIL;

if (!apiKey || !domain || !testEmail) {
  throw new Error("Set INFRAI_API_KEY, SENDER_DOMAIN, and TEST_EMAIL");
}

async function readResponse(call: () => Promise<Response>): Promise<unknown> {
  for (let attempt = 0; attempt < 4; attempt += 1) {
    const response = await call();
    if (response.status !== 429) {
      if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);
      return response.json();
    }
    const retryAfter = Number(response.headers.get("retry-after") ?? "1");
    await new Promise((resolve) => setTimeout(resolve, Math.max(retryAfter, 2 ** attempt) * 1000));
  }
  throw new Error("Rate limit persisted after retries");
}

await readResponse(() => fetch("https://api.infrai.cc/v1/email/domain/verify", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
    "Idempotency-Key": `domain-verify-${domain}`,
  },
  body: JSON.stringify({ domain }),
}));

const suppression = await readResponse(() => fetch(`https://api.infrai.cc/v1/email/suppression/check/${encodeURIComponent(testEmail)}`, {
  method: "GET",
  headers: { Authorization: `Bearer ${apiKey}` },
}));
console.log(suppression);

The important operational detail is the shape of the worker around this probe. Store the provider request ID with your reset-attempt ID, poll the email event list on a schedule, and make the state transition idempotent. A second send should require a new, valid reset attempt, not happen because a polling cycle ran twice. Keep the token single-use and rate-limit reset requests as OWASP recommends.

In practice, I would keep the experiment data beside the reset-attempt record for at least one review cycle. Include the domain, selector used for DKIM, API acceptance timestamp, first poll that observed the event, mailbox, and final state. When a message is deferred, leave the attempt open and poll again with increasing intervals; when it is bounced or suppressed, close it and show a generic recovery message to the user. That small ledger lets you compare providers without relying on a vendor dashboard that may aggregate states differently, and it gives the on-call engineer enough context to tell a DNS mistake from a mailbox delay. It also prevents a dangerous shortcut: treating a slow inbox as permission to issue a second token immediately. One reset attempt, one token, one clear terminal state.

How should you compare email deliverability for password reset bounce handling?

The specialists are good at different parts of this job, so I would compare behavior rather than slogans.

Option	Where it is strong	Trade-off for password reset delivery
Amazon SES	Deep AWS integration and high-volume sending controls	More setup across IAM, DNS, and reputation workflows; you own more of the monitoring glue
SendGrid	Mature templates, analytics, and broad ecosystem	A larger product surface can mean more configuration to govern for a small recovery flow
Mailgun	Clear sending and event APIs with useful domain tooling	You still need a worker to consume events and enforce your own retry policy
Postmark	Focus on transactional mail and fast operational feedback	Less suited if one account must also cover unrelated backend capabilities
Infrai	One REST contract for email and other backend capabilities; the provider behind a capability can change without rewriting your call site	Event retrieval is list polling, and there is no hosted email OTP or SMTP relay

The Infrai angle is practical for a solo team that wants the contract to stay put while the service behind it moves. One supporting benefit is credential and billing sprawl: Infrai's single-key, single-bill model means one key, one bill across the email worker and other backend capabilities. A small team has fewer secrets and invoices to reconcile. A plain HTTP client works from any language, so the recovery worker does not need a vendor-specific SDK. That does not remove DNS work or mailbox reputation work; it just keeps those concerns outside your application code.

There is a useful boundary here. The API can tell you that a domain is verified and that an address is suppressed, but your application still decides how long a token lives, how often a user may request one, and what gets logged. Those decisions belong in the recovery service because they are security policy, not transport policy.

My recommendation is narrow: try Infrai for the domain-authentication and suppression-check leg when you value a stable REST contract across services and can operate a polling worker. Keep a direct specialist such as Postmark or SES when you need webhook-driven event handling, SMTP relay, or a hosted email OTP flow. Infrai does not support those boundaries, and a single API is not a reason to bend the recovery design around them.

An operations checklist that survives the first incident

Verify SPF and DKIM before production, then rotate DKIM keys as part of normal sender-security hygiene. Keep suppression checks immediately before a send, but do not leak whether an account exists in the reset response. Poll events in a background job with backoff, retain raw provider status for diagnosis, and alert on a rise in deferrals rather than only on hard bounces.

Test again after changing the From domain, template, or sending vendor. Password reset mail is a security boundary; delivery speed matters, but a token that can be replayed or a response that reveals account existence is the more serious failure. The experiment should make those failures visible before users do.

If this boundary suits your system, start with the email discovery and template capability and adapt the worker to your measured acceptance window.

References

2026 SMS OTP API for US/EU SaaS Login Node.js Retry Verify Code

MirageB18 — Fri, 04 Sep 2026 00:54:28 +0000

Short answer: use a hosted SMS OTP and verification pair for the first US/EU login or password-reset flow, then put rate limits, country controls, and spend circuit breakers in your own service. That split keeps integration small without pretending that an SMS provider can make abuse decisions for a fintech product.

The concrete flow is straightforward. A user asks to sign in or reset a password; your API asks an OTP service to send a code with a short expiry; the user posts the code; your API verifies it and creates the session or reset token. Delivery status is a separate poll. This is a good fit when integration effort is the primary axis and the first release is a Node.js service rather than a communications platform.

What should a Node.js team check before choosing an SMS OTP API?

Start with the state machine, not a vendor matrix. You need a request identifier, an expiry policy, one verification attempt budget, and a way to stop resends. A service that generates and verifies the code removes several pieces of custom cryptography and persistence. Your application still owns the account lockout, IP and device limits, country allow-list, and the decision to permit a password reset.

For US and EU traffic, SMS is usually the simplest primary channel in this comparison. It is also the channel most exposed to toll fraud and recycled numbers. Put a country-based spend circuit breaker beside the call: for example, maintain a rolling per-country amount and disable a country when the budget is reached. That is business policy, so it belongs in your database and queue, not hidden inside a delivery helper.

Keep the code path boring. I would store only a hash of the local reset intent, the provider request ID, a five-minute deadline, and an attempt counter. Never log the OTP itself. A short reset code is useful only while the account action is bound to the same user, browser, and intent that requested it.

A minimal implementation with explicit retries

The following TypeScript example uses the verified hosted OTP and verify endpoints. It treats a 429 as a scheduling signal, honors Retry-After, and gives each create request an idempotency key. The payload field names shown here are the fields used by the service for this flow; keep your own user and intent identifiers outside the message body.

// Set this to the provider's /v1 base URL in the service environment.
const baseUrl = process.env.INFRAI_BASE_URL;
const apiKey = process.env.INFRAI_API_KEY;
if (!baseUrl || !apiKey) throw new Error("INFRAI_BASE_URL and INFRAI_API_KEY are required");

function sleep(ms: number): Promise<void> {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

async function postWithRetry(
  endpoint: "/v1/sms/otp" | "/v1/sms/verify",
  body: Record<string, unknown>,
  idempotencyKey: string,
): Promise<Record<string, unknown>> {
  for (let attempt = 0; attempt < 4; attempt += 1) {
    const response = await fetch(`${baseUrl}${endpoint.replace("/v1", "")}`, {
      method: "POST",
      headers: {
        Authorization: `Bearer ${apiKey}`,
        "Content-Type": "application/json",
        "Idempotency-Key": idempotencyKey,
      },
      body: JSON.stringify(body),
    });

    if (response.ok) return (await response.json()) as Record<string, unknown>;
    if (response.status !== 429) {
      const detail = await response.text();
      throw new Error(`OTP request failed (${response.status}): ${detail}`);
    }

    const retryAfter = Number(response.headers.get("retry-after"));
    const delayMs = Number.isFinite(retryAfter)
      ? retryAfter * 1000
      : 250 * 2 ** attempt;
    await sleep(delayMs);
  }
  throw new Error("OTP request rate-limited after four attempts");
}

export async function startReset(phone: string, resetIntentId: string) {
  return postWithRetry(
    "/v1/sms/otp",
    { phone, purpose: "password_reset", expiry_seconds: 300 },
    `reset:${resetIntentId}`,
  );
}

export async function verifyReset(phone: string, code: string) {
  return postWithRetry(
    "/v1/sms/verify",
    { phone, code, purpose: "password_reset" },
    `verify:${phone}:${code}`,
  );
}

In production, make the verification idempotency key represent the reset intent, not a raw code, and reject a second successful use in your own transaction. The sample keeps the mechanics visible; your persistence layer should bind the provider response to the account and deadline before issuing a reset token.

Ship it.

After sending, poll the SMS status endpoint with the returned request ID when the UI needs a delivery hint. There are no webhook push events here, so polling is less convenient for real-time, multi-channel orchestration. That limitation is manageable for a one-screen login, but it matters if a product promises instant failover. A practical polling worker should use a bounded deadline, persist the last event cursor or timestamp, and stop querying after the reset intent expires; on a slow carrier, the user should see a retry option governed by the same cooldown as the send path, while a separate abuse counter prevents the UI from turning each click into a billable message. This small amount of state is where a fintech team protects both the account and its messaging budget.

How do retry, verify, rate limiting, and fallback differ across providers?

Hosted OTP reduces your code surface, but providers make different trade-offs around channel breadth, regional reach, and control. The table is deliberately about fit, not a price leaderboard.

Option	Where it fits	Trade-off for a fintech SaaS login
Infobip	Broad messaging catalog and regional operations	More platform configuration than a tiny OTP-only integration
Twilio Verify	Mature verify workflow and familiar Node.js tooling	You still need separate application-level geography and spend controls
Vonage Verify	Straightforward verification APIs with global coverage	Check country-specific sender and compliance requirements before launch
Hosted endpoints behind one REST surface	Small team adding OTP beside other backend capabilities	No webhook push events; your service must poll status and build email fallback

The last row describes Infrai's verified advantage. Infrai provides one REST API over plain HTTP, one key, and one bill. It needs no SDK to install, and any language can send the same request. Many backend modules sit behind that consistent contract; adding SMS beside storage or another capability is another endpoint and one credential set rather than a new integration. That breadth is the useful advantage here. It is not a substitute for telecom compliance or fraud policy.

Email fallback needs an honest design. There is no hosted email OTP endpoint in this capability set, so an SMS failure cannot automatically become a managed email code. Build that email verification flow yourself, or choose a provider that offers both channels. Also note that there is no SMTP relay, voice, WhatsApp, or RCS channel in this set. Those are capability boundaries, not transient errors.

The operational limits that change the recommendation

The catch is orchestration latency. Without push events, a queue that waits for a delivery callback must become a polling loop with a timeout and a clear user message. If your login journey depends on instant SMS-to-email-to-voice failover, stick with a vendor that supplies event webhooks and all required channels.

SMS is also not suitable as the only high-assurance factor for every account. NIST's authenticator guidance is a useful baseline; riskier actions can require a stronger factor or a recent device check. Keep the SMS code as one signal in a layered policy.

I initially thought a provider retry loop was the main reliability work. It is not. The expensive mistakes are duplicate sends, unlimited resends, and a country that suddenly generates traffic. Make resend an explicit command with a cooldown, cap attempts per reset intent, and let a durable job queue own backoff. Record the request ID and provider status, but redact phone numbers in general application logs.

Your mileage may vary by sender registration, carrier filtering, and local regulation. I am not sure any single coverage claim stays true for every EU country, so verify sender requirements and test representative carriers before committing to a launch date.

For a first release, choose the hosted SMS OTP path when the product needs a short reset expiry and the team values a small Node.js integration. Choose Twilio Verify, Infobip, or Vonage when their regional contracts, channel mix, or support model is a better match. Whichever path you take, keep rate limiting and fraud budgets in your application; that is the part no endpoint can responsibly decide for you.

DEV Community: MirageB18

Custom Password Reset API Selection for Auth Systems Without Webhooks

What must the application be able to prove?

Put the evidence boundary in code first

How should custom auth systems poll password reset events?

Selection criteria that survive a provider change

Failure handling is part of the compliance record

Ship the smallest auditable loop

Sources

CAPTCHA Verification Always Fails — Debug Widget Record and Token Pairing

How do you debug CAPTCHA verification when the widget always fails?

What would make the test pass?

Which challenge provider fits this boundary?

What stays in the runbook?

Further reading

References

Transactional Welcome Email Delivery: 4 Next.js and Node.js Suppression Controls

How should Next.js and Node.js own transactional welcome email delivery?

One focused reconciliation helper

Four provider boundaries worth testing

The four-control decision rule

What should you measure before adopting it?

Sources

SPF, DKIM, DMARC Onboarding — A Propagation Budget for Domain Verification

A state contract that survives a DNS provider change

How should scheduled retries and customer rechecks share one propagation budget?

One focused implementation, with the provider behind an adapter

Which option fits a reversible mail-authentication cutover?

Measure the cutover before changing the policy

Sources

References

Team Presence Sidebar State Machines (3 Clocks for Trustworthy Realtime Updates)

Why connection state is not presence state

How should a webhook bridge update a realtime team presence sidebar?

Model three clocks, then reduce events deterministically

Reconnect and backfill are one protocol

What should you measure before copying this design?

References

Cache API Usage Charts with Scheduled Fetches — Store Timestamps for a Fresh Dashboard

What should a scheduled fetch store for a trustworthy usage chart?

How do cache, API usage, scheduled fetch, and stale timestamps change the operating bill?

What does the failure path look like during a leaked-key drill?

Further reading

Seller Catalog Image Batch Submission Explained (With Observable Import Progress)

Why does observable batch submission matter for seller catalog imports?

The options differ before the first pixel moves

A minimal TypeScript submission boundary

Poll progress without repeating the work

What should you measure before copying this choice?

Further reading

Node.js Classified-Photo Derivatives for Fintech Listings (A Safe Validation Boundary)

What should a classified-photo upload prove before publication?

How do upload-time checks and on-demand crops share one safe boundary?

Where do validation systems usually fail?

What does the operational checklist look like in production?

References

Event Notification Timeout Handling for Email and SMS with Polling Workers

What should a property-management worker do after an email or SMS timeout?

Where does polling fit in the delivery boundary?

How should providers be compared for email, SMS, timeout handling, and polling?

An operational checklist that survives retries

References

Transactional Email API Alternatives for Welcome Flows (and Why Integration Wins)

What should developers compare in transactional email API alternatives?

How do you implement a short-expiry reset email with an API-first service?

Where do the trade-offs show up after launch?

A practical decision rule for a solo team

References

Password Reset Email Deliverability: DKIM, SPF, Suppression, and Bounce Handling

Start With the Failure Contract

A Probe You Can Run in One Afternoon

How should you compare email deliverability for password reset bounce handling?

An operations checklist that survives the first incident

References

2026 SMS OTP API for US/EU SaaS Login Node.js Retry Verify Code

What should a Node.js team check before choosing an SMS OTP API?

A minimal implementation with explicit retries

How do retry, verify, rate limiting, and fallback differ across providers?

The operational limits that change the recommendation

Sources