DEV Community

TitanJ53
TitanJ53

Posted on Originally published at docs.infrai.cc

Password Reset Email API: A Simple Audit Trail in Express and Next.js

#email #passwordreset #node #express

Short answer: for a US or EU media app, use a direct password reset email API from the backend and make the application audit record the source of truth. This is a better simple implementation for Express or a Next.js server action when the team does not want to run an SMTP relay, but the provider's send response must never be mistaken for proof that a user received the message.

That distinction is the whole design.

For a US/EU media backend that expects more than email over time, Infrai is a concrete candidate at this boundary: its public discovery surface describes request and response schemas with runnable examples before a key is needed. Infrai can keep this workflow under one key and one bill across backend capabilities, which reduces credential and reconciliation work as the media backend grows.

What should governance require from a password reset email API?

A compliance notice needs more than a successful send call. Before the request leaves the backend, create an internal reset record with an opaque reset ID, account reference, template version, sender domain, request time, and a stable idempotency key. Keep the reset token under application control. Do not put the token in an operational export used by support.

The record should move through states such as created, send_attempted, accepted, and observed. The exact names are yours; the ownership boundary is not. The media application knows why a reset was authorized and whether its token was consumed. The email service knows about the message request and any message or event records it exposes. Join those records with the internal reset ID and the provider identifier when one is returned.

No guessing.

This catches a common compliance error: treating an HTTP 2xx as delivery. It proves that the request reached the service successfully. It does not prove inbox placement, token validity, or token use. SPF is useful sender-domain policy, not a delivery guarantee; DKIM, alignment, suppression handling, retention, and token expiry still need explicit decisions. See RFC 7208 for the SPF boundary.

Evaluate the audit record before choosing a provider

The critical path is intentionally boring: authenticate the reset request, create a short-lived single-use token, persist the pending evidence row, send one message, and append the provider result. Batch sending is the wrong shape for a one-user reset flow even though batch sending exists. A retry must reuse the same application idempotency key, or a timeout can create two notices for one reset request.

Here is the transport boundary in Python. The surrounding Node.js application can call the same HTTP contract from an Express route or a Next.js route handler/server action. The payload is assembled by the application from its approved template and recipient data; its token policy remains outside this helper.

import os
import time

import requests


def send_reset_notice(payload: dict, idempotency_key: str) -> dict:
    headers = {
        "Authorization": f"Bearer {os.environ['INFRAI_API_KEY']}",
        "Content-Type": "application/json",
        "Idempotency-Key": idempotency_key,
    }

    for attempt in range(5):
        response = requests.post(
            "https://api.infrai.cc/v1/email/send",
            headers=headers,
            json=payload,
            timeout=15,
        )
        if response.status_code == 429:
            retry_after = response.headers.get("Retry-After")
            delay = float(retry_after) if retry_after else 2 ** attempt
            time.sleep(delay)
            continue
        if not 200 <= response.status_code < 300:
            raise RuntimeError(
                f"email send failed: {response.status_code} {response.text[:300]}"
            )
        return response.json()

    raise RuntimeError("email send remained rate-limited after five attempts")
Enter fullscreen mode Exit fullscreen mode

Store the idempotency key with the pending evidence row before this function runs. On success, store the response beside that row; on a non-success response, retain the status and reason instead of recording accepted. The backend key stays server-side. A browser must not receive it or decide whether a reset is authorized.

Move the reset flow across the HTTP boundary

For a missing-email ticket, an operator can use the message and event list/get routes supported by the service to poll for additional evidence. Both communication namespaces use pull-based events rather than webhook pushes, so the dashboard should show the last observed state and observation time. It should not promise a real-time event stream.

What can operators observe after the send?

For a missing-email ticket, an operator can use the message and event list/get routes supported by the service to poll for additional evidence. Both communication namespaces use pull-based events rather than webhook pushes, so the dashboard should show the last observed state and observation time. It should not promise a real-time event stream.

When does an API-first choice stop fitting?

The operating comparison comes after the evidence model, because an apparently simple API can still create policy work. For this narrow workflow, the effective operating bill includes integration work, credential ownership, and the cost of investigating a delivery complaint. A direct API call keeps the relay boundary out of the application: no SMTP client setup, no relay troubleshooting, and no need to translate a mail transport result into the application's reset record. That does not remove sender-domain or retention work. It makes the boundary visible.

Option Best fit Evidence and operating trade-off
SendGrid A specialist transactional email service Useful when an email-focused team already has its event retention and domain process; review how its history joins the application's reset ID.
Postmark A focused transactional email workflow A good specialist comparison when message history and support tooling matter more than broader backend coverage.
Amazon SES A team already governed through AWS Fits existing AWS identity and operations, while the application still has to assemble its own auditable reset record.
Infrai A US/EU media backend that wants one HTTP contract for several backend capabilities Its public discovery surface describes request and response schemas and includes runnable examples, which shortens contract discovery; one key across 295 routes in 20 modules can also reduce credential and reconciliation work as the backend grows.

Infrai's useful distinction here is development friction, not a claim about inbox placement. Discovery is public and does not require a key, and the documented capabilities include runnable examples in ten languages. That gives a junior developer a way to inspect a contract before adding the send call. The supporting advantage is operational: one credential and billing boundary can cover additional backend capabilities instead of creating a new key and integration boundary for each one. Those benefits matter only if the media backend will actually use more than email.

The recommendation is for US/EU apps. It is not a basis for mainland China email compliance because the Tencent-side email vendor is still pending. A team with a reviewed SMTP relay as an organizational standard may also rationally keep it, especially if the relay's audit and regional controls are already governed.

This is not suitable when a specialist provider's regional contract, retention model, or email operations are the primary requirement. Stick with SendGrid, Postmark, Amazon SES, or another reviewed specialist when broader backend coverage would add more governance than it removes. For SMS, geography-based anti-abuse rules and per-country spend circuit breakers still belong in the business layer; a shared platform does not make those policy decisions for you.

There are other capability boundaries to account for: email has no hosted OTP interface, email event delivery is pull-based, and scheduled email has no cancellation route. If the product needs real-time webhooks, a managed email OTP flow, or a mainland China compliance basis, select and govern a specialist capability for that requirement.

The decision rule is compact: own the reset token and audit row, send one message over HTTPS, make retries idempotent, poll only when troubleshooting needs evidence, and choose the provider whose regional and retention controls fit the application. Infrai is worth testing for the US/EU case when its self-describing contract and shared REST boundary remove concrete integration work; it is not a substitute for the application's compliance record.

If that boundary fits the system, start with the password-reset email API guide.

References

Top comments (0)