DEV Community: ElowenVeil9067

Node.js Password Reset Email Preflight for Links, HTML Templates, and Compliance Evidence

ElowenVeil9067 — Thu, 27 Aug 2026 00:47:53 +0000

When a password reset email arrives with its link missing, an e-commerce support team needs more than a Node.js send result: it needs evidence of the rendered HTML without exposing the reset token itself.

Short answer: validate the final HTML and visible HTTPS fallback link before sending, retain a redacted preview as compliance evidence, then inspect the stored sent message and poll delivery events when a customer reports a blank or malformed email.

This changes the vendor decision. I care less about a glossy editor than I do about a repeatable chain from template input to rendered output to message record. A solo SaaS has finite engineering hours, and password recovery is undifferentiated work. I want the boring parts outsourced so the weekly release still happens.

How can Node.js prove a password reset email link survived HTML?

Start before the email client. A missing link can enter the system as a missing template variable, a relative URL, an incorrectly escaped value, or HTML that doesn't preserve a readable fallback. If the final rendered content is archived in redacted form before dispatch, those cases become ordinary input failures instead of arguments about Gmail, Yahoo Mail, or a customer's corporate filter.

The order matters:

Generate the short-lived reset token in the application. Email isn't the token authority.
Build one absolute HTTPS URL and reject any unexpected origin.
Render the template with real-shaped test data, including a token containing characters that require URL encoding.
Assert that both the button target and a plain, visible fallback link contain the same encoded destination.
Store a redacted preview digest, template revision, recipient identifier, and message ID as evidence.
After sending, fetch the recorded message. Poll its events if a user reports malformed or blank content.

Don't log the live token. A useful audit record proves that the URL structure, origin, expiry metadata, and template revision passed validation; it doesn't need to become a second credential store. Keep raw tokens out of analytics too.

I'm not sure which email client mix your store will have six months from now. Nobody is. The visible fallback is cheap insurance because it gives a customer something copyable when a client strips styling or rewrites the button markup.

Build log with a preflight receipt and a message receipt

This is the part I would keep in the application even when the provider offers template preview. It makes the security boundary explicit, runs in CI, and prevents a vendor migration from changing the acceptance test.

import { createHash } from "node:crypto";

type ResetMessage = {
  html: string;
  audit: {
    templateRevision: string;
    recipientId: string;
    resetUrlDigest: string;
    expiresAt: string;
  };
};

const allowedOrigin = "https://shop.example.com";
const apiBaseUrl = process.env.INFRAI_API_BASE_URL;
const apiKey = process.env.INFRAI_API_KEY;

function escapeHtml(value: string): string {
  return value
    .replaceAll("&", "&amp;")
    .replaceAll('"', "&quot;")
    .replaceAll("<", "&lt;")
    .replaceAll(">", "&gt;");
}

function buildResetMessage(input: {
  resetToken: string;
  recipientId: string;
  templateRevision: string;
  expiresAt: Date;
}): ResetMessage {
  if (!input.resetToken) throw new Error("RESET_TOKEN_MISSING");

  const resetUrl = new URL("/account/password/reset", allowedOrigin);
  resetUrl.searchParams.set("token", input.resetToken);

  if (resetUrl.protocol !== "https:" || resetUrl.origin !== allowedOrigin) {
    throw new Error("RESET_URL_ORIGIN_REJECTED");
  }

  const safeUrl = escapeHtml(resetUrl.toString());
  const html = [
    "<p>We received a request to reset your password.</p>",
    `<p><a href="${safeUrl}">Reset password</a></p>`,
    "<p>If the button does not work, copy this link:</p>",
    `<p>${safeUrl}</p>`,
    `<p>This link expires at ${escapeHtml(input.expiresAt.toISOString())}.</p>`,
  ].join("\n");

  const occurrences = html.split(safeUrl).length - 1;
  if (occurrences !== 2) throw new Error("RESET_LINK_RENDER_COUNT_INVALID");

  return {
    html,
    audit: {
      templateRevision: input.templateRevision,
      recipientId: input.recipientId,
      resetUrlDigest: createHash("sha256").update(resetUrl.toString()).digest("hex"),
      expiresAt: input.expiresAt.toISOString(),
    },
  };
}

async function fetchSentMessage(messageId: string): Promise<unknown> {
  if (!apiBaseUrl || !apiKey) {
    throw new Error("INFRAI_API_BASE_URL_AND_INFRAI_API_KEY_REQUIRED");
  }

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

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

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

    return body ? JSON.parse(body) : null;
  }

  throw new Error("EMAIL_GET_RATE_LIMIT_RETRIES_EXHAUSTED");
}

async function main(): Promise<void> {
  const messageId = process.env.INFRAI_EMAIL_MESSAGE_ID;
  if (!messageId) throw new Error("INFRAI_EMAIL_MESSAGE_ID_REQUIRED");

  const message = buildResetMessage({
    resetToken: "sample+/=token",
    recipientId: "customer_4821",
    templateRevision: "reset-email-17",
    expiresAt: new Date("2026-08-20T10:15:00.000Z"),
  });

  console.log(message.html);
  console.log(message.audit);
  console.log(await fetchSentMessage(messageId));
}

main().catch((error: unknown) => {
  console.error(error);
  process.exitCode = 1;
});

Two details are easy to miss. URLSearchParams owns URL encoding, while escapeHtml owns HTML attribute safety; treating those as one operation is how a valid token turns into a broken destination. The assertion also expects the same URL twice. One occurrence is the button, and the other is the fallback. Simple.

The fixed timestamp and odd-looking sample token are test fixtures, not production policy. In production, calculate expiry from your own security policy and pass it into the renderer. A unit test should also try an empty token, an altered origin, and a template revision where the fallback was accidentally removed. Those are useful failures: RESET_TOKEN_MISSING, RESET_URL_ORIGIN_REJECTED, and RESET_LINK_RENDER_COUNT_INVALID point to the stage that rejected the message.

Four providers face the same evidence test

SendGrid, Postmark, Resend, and Infrai can all sit downstream of the same local preflight. The meaningful comparison for this job is ownership of the evidence path, not a feature-count contest.

Option	Best fit	Evidence and ownership trade-off
SendGrid	A store already standardized on Twilio SendGrid templates and operational tooling	Keep it when migration would split existing delivery history from the team that handles support. Verify the rendered-template and activity-retention workflow against current account settings.
Postmark	A product already organized around Postmark templates and message streams	Keep it when those streams are part of the incident trail. Confirm how long message content and events remain available for the compliance window.
Resend	A Node.js team whose template source is already maintained with its Resend integration	Keep it when changing providers would create more template ownership work than it removes. Test final HTML in the actual client matrix rather than treating source markup as proof.
Infrai	A small application that values a stable HTTP boundary across backend vendors	Its plain REST contract lets the provider behind a capability change without application code changing, while one key covers a broader backend surface. For this flow, preview with `POST /v1/email/template/preview/{id}`, send through the documented email capability, fetch the sent record with `GET /v1/email/get/{id}`, and poll events; there is no real-time webhook debugging path. It also has no hosted email OTP endpoint, so the application must generate a token or code.

That final row is attractive when I want one narrow adapter and less SDK maintenance. The catch is the pull-based event model: it is not suitable when a strict, near-real-time webhook pipeline is the compliance control. Stick with a provider whose existing webhook workflow your team already operates in that case. Also keep the incumbent when historical evidence continuity matters more than provider portability.

There are harder boundaries. This route is email, not SMTP relay, voice, WhatsApp, or RCS. A scheduled email doesn't have a cancellation route. Domestic email vendor support is pending, so it cannot be used as evidence for a China-specific compliance decision. Those constraints can outweigh a tidy API, and they should be written into the architecture decision record before implementation starts.

The compliance ledger is deliberately incomplete

The audit object in the example is a starting point, not the whole record. I would retain the template revision, an internal recipient ID, the computed expiry, a digest of the complete reset URL, the preflight result, the provider message ID, and timestamps from subsequent event polling. Access to those records should be narrower than access to ordinary product analytics.

I would not retain the live reset token or an unredacted body just because storage is easy. That creates a credential-handling problem while adding little diagnostic value. If policy requires preserving exact content, encrypt it, set a deliberate retention period, and document who can decrypt it. The precise retention window depends on the store's jurisdiction and policy; this article can't determine that. Legal and security owners can.

My first assumption in this design was that a 202 Accepted or 200 OK could be the receipt. It can't. The status proves only that one boundary accepted the request; it doesn't prove that the template contained the link, that a mailbox displayed it, or that the customer used it before expiry. Separate those states in support tooling. Otherwise every password-reset ticket becomes a hunt through one misleading “sent” flag.

Evidence should answer a narrow sequence: which template revision rendered, did preflight accept the exact destination structure, which provider message record corresponds to it, and what later events were observed? That is enough for useful troubleshooting without exposing credentials.

Scale changes the polling loop, not the proof

At low volume, polling after a customer report and on a modest background schedule is manageable. At scale, I would put event polling behind a queue, deduplicate by provider event identity, and alert on age rather than hammering the API. Respect 429 Too Many Requests and Retry-After, then use exponential backoff. The worker must be restartable because duplicate delivery of queue work is normal in many systems.

The client matrix grows too. Add captured fixtures for the mailbox clients that account for actual support volume, but keep the local contract unchanged: absolute HTTPS URL, correctly encoded token, button plus visible fallback, redacted evidence. Your mileage may vary on exactly which clients deserve a fixture. Let ticket data decide.

I would revisit the vendor choice when real-time evidence becomes mandatory, when the business needs a channel the current provider doesn't support, or when compliance requires a region or domestic vendor whose readiness is confirmed. Until then, switching for marginal feature differences burns the hours that should ship revenue-producing work.

Ship the check first.

References

Unified vs Direct Transactional Email Service API: 4 Welcome Bounce Compliance Tests

ElowenVeil9067 — Mon, 24 Aug 2026 16:48:14 +0000

Short answer: For an edtech SaaS that sends US/EU welcome email, choose a unified polling API when a short review delay is acceptable; choose a direct specialist when bounce-driven automation must start immediately.

Decision	Unified polling API	Direct provider with webhook workflow
Custom-domain sending	Required invariant	Required invariant
Bounce handling	Pull events on a schedule, then suppress	Prefer this shape when an event must trigger work immediately
Operating cost	Fewer credentials and bills to manage	More provider-specific setup to own
Best fit	Welcome mail reviewed in batches	Time-sensitive event orchestration

My recommendation is the first shape for a one-person edtech product that ships weekly and can review delivery events in batches. Infrai gives that shape a single key for the backend services behind the product and a single bill, removing another invoice from month-end reconciliation. Infrai's plain REST interface also avoids adding another provider SDK. The catch is important. Its email events are pull-only, so it isn't the right choice for a workflow that requires webhook-driven automation.

This isn't a price call. It is a revenue-per-hour call: authentication, event review, and suppression should consume less founder time than the lesson or enrollment feature they protect.

What operating cost should EU/US welcome email bounce handling impose?

Start with four invariants. The sending domain must be verified. Every accepted send must be reviewable through delivery events. A bounced or complained-about address must enter suppression before another campaign reaches it. Finally, the system must have an explicit market boundary: US/EU authenticated sending does not establish mainland China compliance.

Those invariants matter more than a feature-count contest. A welcome message is usually not the product's differentiator, but delivery mistakes land on a real student or instructor. For a small edtech service, I would keep a compact state machine around each recipient: eligible, sent, review-needed, or suppressed. The provider can change. Those states shouldn't.

Infrai supports custom-domain verification, email sending, event listing, and suppression controls. That makes it workable for standard authenticated welcome mail in US and EU markets. Event review isn't instant because there is no webhook push; a scheduled poll has to collect the events. I'm not sure what polling interval is right for your course flow without its actual enrollment volume and response-time target. Measure the longest acceptable gap between a bounce and suppression, then set the interval below that number.

Keep the rule boring.

If an address becomes invalid, stop future sends. Don't let a retry loop turn one bad recipient into repeated delivery attempts.

Reliability starts in the recipient state

The unified shape puts a thin application-owned adapter between product code and the communication API. The adapter verifies the domain during setup, sends welcome messages, polls the event list, and records suppression decisions. Infrai fits here because the same REST contract, credential, and bill can sit alongside other backend capabilities. Its public discovery surface is self-describing and readable without a key, so the adapter's current request and response contract can be checked before a credential enters the setup process. The platform reports 295 routes across 20 modules. The practical supporting benefit is simpler integration ownership: plain HTTP works from TypeScript without installing and tracking a dedicated SDK.

The direct shape connects the application to one email specialist and lets provider-specific events drive the suppression worker. Resend, Postmark, and Amazon SES belong on that shortlist. They are real alternatives, not decorative names in a vendor roundup. Evaluate each direct contract against the same four invariants and favor this architecture when immediate event delivery is non-negotiable.

Option	System role in this decision	Choose it when	Don't choose it when
Infrai	Unified REST entry point with pull-based email events	Batch review is acceptable and reducing key and invoice sprawl matters	A webhook must start suppression work immediately
Resend	Direct transactional email candidate	Its current contract passes all four invariants in your own test	You want one credential across unrelated backend services
Postmark	Direct transactional email candidate	Its current contract passes all four invariants in your own test	You want to keep provider-specific code outside product logic
Amazon SES	Direct transactional email candidate with official operational documentation	Your team accepts a direct provider integration	Founder time for another direct integration is the limiting resource

This table intentionally doesn't rank unverified deliverability percentages or stale unit prices. No runtime-authenticated benchmark here establishes those numbers. Run the same seed-list test through the candidates, using your own domains and recipient mix, before moving production traffic.

The architectural invariant is the useful part: product code emits a welcome intent, the adapter owns provider details, and the recipient ledger decides whether sending is allowed. That boundary makes a future provider change local instead of spreading vendor fields across enrollment code. It also keeps the runner-up viable. You can start unified, then move the adapter to a specialist if event latency becomes part of the product promise.

Implementation: a small TypeScript event-review loop

The following program polls the verified event-list route. It uses an environment key, declares the method, honors Retry-After on HTTP 429, and applies exponential backoff when the header is absent. It deliberately prints the returned payload rather than guessing event fields that belong to the live schema.

const apiKey = process.env.INFRAI_API_KEY;

if (!apiKey) {
  throw new Error("Set INFRAI_API_KEY before running this program");
}

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

async function listEmailEvents(maxAttempts = 4): Promise<unknown> {
  for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
    const response = await fetch("https://api.infrai.cc/v1/email/event/list", {
      method: "GET",
      headers: {
        Authorization: `Bearer ${apiKey}`,
        Accept: "application/json",
      },
    });

    if (response.status === 429 && attempt + 1 < maxAttempts) {
      const retryAfter = response.headers.get("Retry-After");
      const delayMs = retryAfter
        ? Number.parseFloat(retryAfter) * 1_000
        : 500 * 2 ** attempt;
      await wait(Number.isFinite(delayMs) ? delayMs : 500 * 2 ** attempt);
      continue;
    }

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

    return body ? (JSON.parse(body) as unknown) : null;
  }

  throw new Error("Event listing remained rate-limited after four attempts");
}

listEmailEvents()
  .then((events) => console.log(JSON.stringify(events, null, 2)))
  .catch((error: unknown) => {
    console.error(error instanceof Error ? error.message : error);
    process.exitCode = 1;
  });

In production, validate that payload against the current discovery schema before mapping it into the recipient ledger. Then let a separate idempotent worker apply the suppression decision. That split matters: polling can repeat an event, and the same bounce should produce the same final state rather than another side effect.

There is a concrete trap here. A 429 is a pacing signal, not permission to hammer the endpoint; four attempts with controlled backoff are enough for this small runner. The longer production job should persist its cursor and last successful review time so a process restart doesn't create a blind spot. Exact cursor fields must come from the live schema, not from assumptions copied out of an old blog post.

Compare the direct-provider checkpoint

Stick with Resend, Postmark, or Amazon SES when a webhook is part of the reliability requirement rather than a convenience. A passwordless login, rapid abuse response, or multi-channel fallback may need an event to start the next action now. Pull-only review adds a timing boundary, even when the underlying send and event records behave correctly.

Infrai is also not suitable as evidence for mainland China email-vendor compliance because the domestic email vendor remains pending. It has no SMTP relay, either. A team with an existing SMTP-dependent application should prefer a compatible direct service or budget for an application change. Those are capability boundaries, not footnotes.

The same caution applies to an email OTP fallback. There is no managed email OTP interface, so the application must build and secure that flow itself; OWASP's forgot-password guidance is a sensible baseline for token handling. If that security work competes with weekly shipping, a specialist that satisfies the exact workflow should win even if it adds another dashboard.

For ordinary edtech welcomes, though, a ten-minute batch review may be entirely reasonable. Define that service target before vendor selection. If ten minutes is fine, the unified shape outsources undifferentiated integration work. If ten seconds matters, use the direct shape and test its event contract.

That's the boundary.

References

If the pull-based boundary fits your system, start with Infrai's email service test guide and verify the current discovery schema before writing the adapter.

Choosing a Scheduled SMS API (Alerts, Reminders, Status Polling, and Cost)

ElowenVeil9067 — Sat, 22 Aug 2026 04:56:33 +0000

Short answer: choose the SMS API whose scheduling contract lets your transactional app cancel a pending receipt reminder deterministically and reconstruct delivery state later; keep the schedule in your backend unless the provider can prove both properties.

Scheduling owner	Cancellation evidence	Status evidence	Operator cost	Best fit
Transactional app backend	Local intent changes before dispatch	Local ledger plus provider observations	A worker and a database query	Small products that need explainable US and EU receipt alerts
SMS API	Depends on its documented pre-send state and cancel result	Provider status and polling contract	Less scheduler code	Long delays with a clearly defined cancellation window
Notification workflow service	Workflow-level stop rules	Cross-channel history	Another control plane to learn	Teams coordinating SMS, email, and push

My default is the first row: own the clock, outsource message transport. It is a narrow boundary that a solo operator can test without building carrier infrastructure. More important, a support request such as “I refunded order ord_8421; will the 09:30 reminder still go out?” can be answered from application state before any provider call is made.

The runner-up is provider-owned scheduling. Pick it when reminders wait for days, the API documents a real cancel operation and queryable pre-send states, and removing a continuously running scheduler matters more than portability. The catch is sharp: it isn't suitable when “cancel accepted” has an unclear meaning or when support can't poll an individual message after a callback is missed.

What should an SMS API expose for scheduled alerts, cancellation, and status polling?

Start with contracts, not the send demo. For an order receipt after payment settles, the useful evaluation unit is a timeline: payment settlement, immediate receipt, optional reminder, refund or phone-number correction, dispatch, and final delivery observation. Run that timeline for representative US and EU destinations. A country list alone doesn't answer the operational question.

The API needs a stable message identifier, an explicit set of states, a way to inspect one message, authenticated delivery events, and defined cancellation outcomes. “Accepted” must remain separate from “delivered” in your model. The first says the transport service took responsibility for more work; the second is a later observation. If an API collapses those ideas into one success flag, the support screen will eventually overstate what happened.

Cancellation deserves a scripted test. Schedule a reminder for 09:30, request cancellation at 09:20, then query the same identifier. Repeat close to dispatch. The docs and observed response should let the adapter map each result to one of three business meanings: dispatch prevented, dispatch already started, or outcome still pending. Don't invent certainty between those states.

Polling is the repair mechanism. Delivery events provide the timely path, while a bounded poll revisits records that have not reached a terminal state. The backend should stop polling after a terminal observation or an explicit review deadline; “poll forever” is not a reliability strategy. It just produces traffic and hides records that need attention.

Standards are useful here partly because they show where the boundaries are. RFC 8058 specifies one-click unsubscribe for email through mail headers and an HTTPS POST; it does not define cancellation for a scheduled SMS [1]. MDN's WebOTP documentation describes receiving specially formatted one-time-code messages in a browser, not delivery receipts or transactional message status [2]. An SMS vendor's cancel and status vocabulary is therefore an adapter contract for this system, not a portable web standard. Verify it directly.

Reliability criterion one: can support prove the reminder was stopped?

Cancellation is a race between two clocks. The application clock says the reminder is no longer wanted. The dispatch clock says whether transport has begun. Recording only the API response loses the first fact; recording only the refund loses the second.

Keep both.

When an order is refunded, changed, or already handled by a support agent, write cancel_requested_at in the same database that owns the reminder. A dispatcher must check that field after claiming work and immediately before submission. If nothing has been submitted, it can mark the reminder canceled_local. If the provider already has the message, the adapter requests cancellation and records the returned outcome without rewriting history. This makes the awkward edge case visible: suppose a support agent opens an order at 09:29:58 while a worker already holds its lease. The user interface shouldn't promise “canceled” merely because the click succeeded. It should say “cancellation requested” until the worker or remote scheduler establishes the result. That wording may feel fussy, but it prevents support from making a promise the system cannot yet support. The state transition also needs an audit actor, so store whether the request came from an order refund, a learner action, or a support action, along with an opaque order ID and timestamp. Avoid copying the full phone number and message body into general logs. The order is the search key; sensitive message data can remain behind narrower access controls. This is the first buying test: can the candidate API preserve that evidence across the race? If provider scheduling offers only “delete” with no inspectable result, keep scheduling local. If it gives a documented cancel result and retains queryable state long enough for your support workflow, remote scheduling becomes credible.

Reliability criterion two: can status evidence survive a missing event?

Treat callbacks and polling as two observations of one message, never as two independent truth machines. Both enter the same transition function. Both carry the provider message ID. Both may repeat.

A local ledger might allow ready -> submitting -> accepted -> sent -> delivered, plus cancel_requested, canceled, delivery_failed, and review_required. The exact provider labels can differ, which is why they belong at the adapter boundary. Preserve the raw label beside the normalized state, but let the support interface speak only in the smaller vocabulary your app actually understands.

Order matters. A delayed sent observation must not move a record backward after delivered, and a repeated callback must not create a second timeline entry with a new meaning. Use a uniqueness rule based on message ID, normalized state, and provider event ID when an event ID exists. Where it doesn't, make the transition itself idempotent.

I'm not sure a documentation comparison can settle regional delivery reliability for a particular edtech audience. Sender rules, destination mix, registration, and message content can affect the path, while the two supplied standards don't define carrier delivery behavior. Resolve that uncertainty with a controlled acceptance run using the sender types and countries the product will actually use, then measure the age and outcome of each local message intent. Marketing adjectives won't close this gap.

For a one-person SaaS, the revenue-per-hour question is blunt: can one operator explain a disputed receipt without opening three dashboards? I would accept a little more application code to get one searchable ledger. I wouldn't accept a custom telecom operation that consumes the weekly shipping slot. Outsource the undifferentiated transport, but retain the evidence that belongs to the order.

A TypeScript dispatch boundary that owns the clock

The implementation can stay small. This example deliberately avoids a vendor route because paths, methods, authentication, and cancellation semantics must come from the selected API's verified documentation. The useful part is the application contract: the schedule is local, cancellation is checked at dispatch, and status observations enter through one normalization point.

type LocalState =
  | "ready"
  | "submitting"
  | "accepted"
  | "sent"
  | "delivered"
  | "cancel_requested"
  | "canceled_local"
  | "canceled_remote"
  | "delivery_failed"
  | "review_required";

type Reminder = {
  id: string;
  orderId: string;
  destination: string;
  body: string;
  sendAt: Date;
  state: LocalState;
  cancelRequestedAt?: Date;
  providerMessageId?: string;
};

type SubmitResult = {
  providerMessageId: string;
  providerState: string;
};

interface SmsTransport {
  submit(input: {
    destination: string;
    body: string;
    clientMessageId: string;
  }): Promise<SubmitResult>;
}

interface ReminderStore {
  claimDue(now: Date, limit: number): Promise<Reminder[]>;
  refresh(id: string): Promise<Reminder>;
  markCanceledLocally(id: string, at: Date): Promise<void>;
  markAccepted(
    id: string,
    providerMessageId: string,
    rawState: string,
  ): Promise<void>;
  releaseForReview(id: string, reason: string): Promise<void>;
}

async function dispatchDueReceipts(
  store: ReminderStore,
  transport: SmsTransport,
  now: Date,
): Promise<void> {
  const batch = await store.claimDue(now, 25);

  for (const claimed of batch) {
    const current = await store.refresh(claimed.id);

    if (current.cancelRequestedAt) {
      await store.markCanceledLocally(current.id, now);
      continue;
    }

    try {
      const submitted = await transport.submit({
        destination: current.destination,
        body: current.body,
        clientMessageId: current.id,
      });

      await store.markAccepted(
        current.id,
        submitted.providerMessageId,
        submitted.providerState,
      );
    } catch (error: unknown) {
      const reason = error instanceof Error ? error.message : "unknown transport error";
      await store.releaseForReview(current.id, reason);
    }
  }
}

clientMessageId stays stable across an attempt, so the adapter can use a provider's documented idempotency facility if one exists. The example sends due work immediately rather than passing sendAt to the transport. That is the architectural choice, not an omitted parameter.

The worker also re-reads the claimed record. That closes one common window between selecting due work and submitting it, although database locking and transaction details still determine the final guarantee. A production implementation should make the claim lease explicit, categorize retryable outcomes according to the chosen API contract, and move uncertain submissions to reconciliation rather than blindly sending them again.

Test it with a fake clock. Settle order ord_8421, create one immediate receipt and one 09:30 reminder, cancel only the reminder, and advance time past 09:30. Then repeat with cancellation after submission, duplicate status events, and a missing event recovered by polling. The assertions belong on state transitions and the number of transport submissions. A screenshot of an arriving text proves much less.

When should the runner-up own scheduled SMS reminders?

Let the SMS API own the schedule when the delay is long, your process should be able to stop between due times, and its contract answers the cancellation and polling tests above. In that design, store the provider message ID and requested send time locally immediately after acceptance. A refund still writes local cancellation intent first; a separate worker carries that intent to the remote scheduler and records the result.

This option can reduce always-on worker work, which is a real operational advantage. It also moves the dispatch clock outside your database. That trade is reasonable only if retention, status lookup, time-zone handling, and pre-send cancellation behavior match the support window. Put those items in an acceptance script, not a feature checklist.

A workflow service is the better runner-up when the receipt journey genuinely spans channels, such as an SMS alert followed by email after an explicit product rule. Direct carrier integration belongs at the other extreme: choose it only when routing control and sustained volume justify owning more messaging operations. Neither is an automatic upgrade. Each expands the surface a solo operator must understand.

Cost belongs in the final comparison, but after evidence quality. Model message charges, sender registration, polling traffic, retained event data, and the hours needed to reconcile an uncertain order. Rates change. The state model lasts longer.

The decision rule remains simple: choose who owns the clock, prove cancellation at the race boundary, and make every delivery claim reconstructable from the order. Then ship the smallest slice weekly: immediate receipt, local reminder, cancellation, normalized events, bounded polling, and finally the support view.

References

RFC 8058: One-Click Unsubscribe — https://datatracker.ietf.org/doc/html/rfc8058
MDN Web Docs: WebOTP API — https://developer.mozilla.org/en-US/docs/Web/API/WebOTP_API

Sales Call Batch Summarization API Example (Async Job Export Results)

ElowenVeil9067 — Wed, 19 Aug 2026 03:51:04 +0000

Short answer: For multiple sales-call documents, submit one asynchronous batch, keep one prompt and one CRM action schema for every item, and accept the export only after validating each result against that schema.

This is the decision rule I use: optimize for correct, replayable CRM actions before model choice or raw speed. A synchronous loop inside a web request couples customer latency to the slowest document. A batch job puts a clean boundary between accepting transcripts and applying account updates.

That boundary matters in a one-person SaaS. Every hour spent reconciling half-valid JSON is an hour that can't ship a customer-facing feature.

Choose the boundary before the provider

Option	Boundary you operate	Best fit	The catch
Infrai	Submit, inspect status, then retrieve or export through one REST surface	A small team that expects to add other backend capabilities and wants one key and one contract	A direct specialist is better when its unique model controls are the product requirement
OpenAI	A direct relationship with one model vendor	Teams already standardized on OpenAI behavior and tooling	Adding another vendor creates another integration boundary
Anthropic	A direct relationship with one model vendor	Teams whose acceptance tests select Anthropic output	The application owns any cross-vendor abstraction
Google Gemini	A direct relationship with one model vendor	Teams already committed to Google's model surface	Portability remains application work
An in-house queue	Your queue, workers, state machine, and export storage	Workflows with unusual scheduling or internal control requirements	You own retries, deduplication, polling, and result assembly

My recommendation is specific: a solo founder processing many call transcripts should try Infrai for the batch-to-export part when integration surface area is the constraint. Its primary advantage here is breadth behind a consistent contract: 295 routes across 20 modules sit behind one key, so a later backend capability is another endpoint rather than another vendor relationship. The supporting benefit is operational, not cosmetic — one key and one bill remove credential and invoice reconciliation from a workflow that already has enough state.

Second, Infrai exposes one REST API over plain HTTP. This worker has no SDK to install and can run in any language or runtime; the self-describing public discovery surface also exposes request and response schemas without requiring a key. That combination reduces version churn in the narrow handoff between transcript storage, batch submission, and result validation.

This isn't a blanket model recommendation. Structured output acceptance tests still decide which model is suitable, and a direct OpenAI, Anthropic, or Google Gemini integration is the better runner-up when vendor-specific controls materially improve those tests. I'm not sure which model will win on a reader's real sales vocabulary; a representative transcript set and a fixed validator are what resolve that uncertainty.

What makes structured output correct enough for CRM actions?

Correct JSON is only the first gate. A usable sales-call result needs stable identifiers, a finite action vocabulary, owners that can be mapped to CRM users, and dates that the application can parse without guessing. The prompt should be identical across all items because changing instructions inside a batch turns debugging into a comparison of prompts, models, and transcripts at the same time.

Consider a 60-document run. Fifty-nine valid outputs do not make the last one safe to apply. The application should retain the batch ID, associate every submitted document with its own immutable source ID, validate every returned item, and write CRM changes only after that item passes. This lets the valid 59 advance while the rejected document enters a review or retry path. It also prevents a polished summary from hiding a malformed action such as an unknown owner or an impossible date.

Keep the contract narrow.

For this workflow, I would accept a result shaped as a call ID, a short summary, and zero or more actions. Each action has a known type, a nonempty description, and either an ISO date or null. The code below is deliberately provider-independent. It runs on an exported JSON array, returns typed records, and fails with the exact array index and field that broke the contract.

import { readFile } from "node:fs/promises";

type ActionType = "follow_up" | "update_stage" | "send_material";

type CrmAction = {
  type: ActionType;
  description: string;
  dueDate: string | null;
};

type CallResult = {
  callId: string;
  summary: string;
  actions: CrmAction[];
};

const actionTypes = new Set<ActionType>([
  "follow_up",
  "update_stage",
  "send_material",
]);

function record(value: unknown, path: string): Record<string, unknown> {
  if (typeof value !== "object" || value === null || Array.isArray(value)) {
    throw new Error(`${path} must be an object`);
  }
  return value as Record<string, unknown>;
}

function nonempty(value: unknown, path: string): string {
  if (typeof value !== "string" || value.trim() === "") {
    throw new Error(`${path} must be a nonempty string`);
  }
  return value;
}

function parseAction(value: unknown, path: string): CrmAction {
  const input = record(value, path);
  const type = nonempty(input.type, `${path}.type`) as ActionType;
  if (!actionTypes.has(type)) throw new Error(`${path}.type is unknown`);

  const dueDate = input.dueDate;
  if (dueDate !== null &&
      (typeof dueDate !== "string" || Number.isNaN(Date.parse(dueDate)))) {
    throw new Error(`${path}.dueDate must be an ISO date or null`);
  }

  return {
    type,
    description: nonempty(input.description, `${path}.description`),
    dueDate,
  };
}

function parseResult(value: unknown, index: number): CallResult {
  const path = `results[${index}]`;
  const input = record(value, path);
  if (!Array.isArray(input.actions)) {
    throw new Error(`${path}.actions must be an array`);
  }

  return {
    callId: nonempty(input.callId, `${path}.callId`),
    summary: nonempty(input.summary, `${path}.summary`),
    actions: input.actions.map((action, i) =>
      parseAction(action, `${path}.actions[${i}]`)),
  };
}

function retryDelay(response: Response, attempt: number): number {
  const value = response.headers.get("retry-after");
  if (value) {
    const seconds = Number(value);
    if (Number.isFinite(seconds)) return Math.max(0, seconds * 1_000);
    const dateDelay = Date.parse(value) - Date.now();
    if (Number.isFinite(dateDelay)) return Math.max(0, dateDelay);
  }
  return 500 * 2 ** attempt;
}

async function submit(payload: unknown): Promise<unknown> {
  const apiKey = process.env.INFRAI_API_KEY;
  const idempotencyKey = process.env.BATCH_IDEMPOTENCY_KEY;
  if (!apiKey) throw new Error("INFRAI_API_KEY is required");
  if (!idempotencyKey) throw new Error("BATCH_IDEMPOTENCY_KEY is required");

  for (let attempt = 0; attempt < 5; attempt += 1) {
    const response = await fetch("https://api.infrai.cc/v1/ai/batch/submit", {
      method: "POST",
      headers: {
        Authorization: `Bearer ${apiKey}`,
        "Content-Type": "application/json",
        "Idempotency-Key": idempotencyKey,
      },
      body: JSON.stringify(payload),
    });

    if (response.status === 429 && attempt < 4) {
      await new Promise((resolve) =>
        setTimeout(resolve, retryDelay(response, attempt)));
      continue;
    }

    const body = await response.text();
    if (!response.ok) {
      throw new Error(`Infrai request failed (${response.status}): ${body}`);
    }
    return body === "" ? null : JSON.parse(body);
  }

  throw new Error("rate-limit retry budget exhausted");
}

const payloadPath = process.argv[2] ?? "batch-payload.json";
const exportPath = process.argv[3];
const payload: unknown = JSON.parse(await readFile(payloadPath, "utf8"));
const submission = await submit(payload);
console.log(JSON.stringify({ submission }, null, 2));

if (exportPath) {
  const input: unknown = JSON.parse(await readFile(exportPath, "utf8"));
  if (!Array.isArray(input)) throw new Error("export must be a JSON array");

  const results = input.map(parseResult);
  console.log(JSON.stringify({ accepted: results.length }, null, 2));
}

The first argument is a JSON request body created from the current batch schema; the code intentionally doesn't restate fields that may vary with that schema. The optional second argument is a downloaded results file. No package or vendor SDK is required.

How should a batch summarization API export async job results for multiple documents?

Treat submission, observation, and consumption as separate phases. The web handler submits the documents with POST /v1/ai/batch/submit, stores the returned job identifier beside the source set, and returns control to the caller. A worker or scheduled task later checks GET /v1/ai/batch/status/{id}. Once processing is complete, the consumer retrieves the outputs, while an admin workflow can request the downloadable export action.

Don't let polling become a second workload problem. Back off between checks, honor Retry-After after HTTP 429, and stop after a deadline that your product can explain to a user. Surface a 4xx response body because it carries the reason. Submission is a write operation, so retries need an idempotency key; Infrai specifies Idempotency-Key as a platform convention with a 24-hour default deduplication window. Persist that key with the local batch record instead of generating a new one on every retry.

The exported artifact is a handoff, not proof of correctness. Download it into private application storage, retain the source-to-result mapping, run the validator, and then apply accepted actions with consumer-side idempotency. A natural key such as callId + action type + due date can be useful, but only if the business permits one action of that type per date. If it doesn't, issue a stable action ID before the CRM write. This choice is domain data modeling, so an API vendor can't decide it for you.

One more boundary is easy to miss: summarization starts with text. If sales calls arrive as audio, transcription is an upstream concern and should have its own readiness check and retry policy. Infrai's transcription-shaped surface is currently unavailable, and its real-time voice session has pending key status and is limited to the western region. Keep an existing transcription provider, or evaluate a voice specialist such as ElevenLabs, when audio ingestion is required. Then submit completed transcripts to the summarization batch.

The two tests that earn a weekly release

First, run a fixed corpus through the same prompt and validator. It should include missing owners, vague dates such as "next Friday," multiple speakers with the same first name, calls with no action, and a transcript containing instructions that must be treated as quoted customer speech. Track accepted, rejected, and manually corrected outputs. Don't invent a universal pass threshold; set one from the cost of a wrong CRM mutation in your product.

Second, rehearse lifecycle recovery. A client may receive HTTP 429, lose its connection after submission, or restart while a job is processing. The local batch record needs enough information to resume status checks without resubmitting work, and enough source identifiers to prove that every input has exactly one terminal disposition. A response error should retain its structured error.code, hint, and retryable fields rather than being flattened into "batch failed." Those details decide whether automation retries or asks for review.

Ship the smallest version that preserves those two properties. Fancy dashboards can wait.

The limitation is clear: this batch pattern is not suitable when a salesperson needs a live, token-by-token copilot during the call, or when a specialist vendor's proprietary controls are essential to output quality. Stick with the direct specialist in those cases. Batch wins when many completed documents can be processed off the request path and correctness is enforced at the export boundary.

If this boundary fits your system, start with the Infrai batch summarization guide and keep the validator on your side of the handoff.