Short answer: keep password-reset state in the Node.js application, send through a transactional email API behind an outbox worker, and make each token link opaque, short-lived, and single-use. Custom-domain authentication with SPF, DKIM, and DMARC protects deliverability, but it does not make an email credential trustworthy; only the redemption transaction can do that.
That separation is the useful architecture decision. Mail transport has retries, scanners, bounces, and rate limits. Recovery state needs deterministic rules. A reset request should therefore create one durable intent and one credential record, while the delivery layer remains replaceable.
Decision record: invariants and failure boundaries
The public endpoint returns the same response for an existing and an unknown address. It validates the request, records an outbox item, and returns. It does not wait for DNS, an API response, or a mailbox. This prevents account enumeration and keeps web latency independent of delivery.
The application owns the token lifecycle. Store a digest of the random token, its purpose, expiry, user reference, and a used marker. Put the raw value only in the URL sent to the recipient. Redemption hashes the submitted value and atomically changes the unused row to used while changing the password. A second click loses that race. No transport callback is allowed to extend token lifetime or mark it valid.
The worker owns rendering and transport. It receives a versioned template name and a constrained variable map, not arbitrary values from a controller. The reset origin comes from an allowlist in deployment configuration, requires HTTPS, and is never copied from request input. Logs carry a request or outbox identifier and a redacted recipient hash; they never carry the token or complete link.
Delivery is evidence, not authority.
Rate limits should cover several signals: account, normalized destination, source IP, and broader traffic patterns. Exact thresholds depend on the abuse model, so I'm not sure a number copied from a consumer app belongs in a workforce system. Your mileage may vary. The important invariant is that throttling does not turn the response into an account-existence oracle.
How should a password reset email flow in Node.js handle API tokens and links?
Treat the reset link as data. Render an escaped HTML attribute and a plain-text alternative from one canonical URL. Do not place an email address, internal user ID, or authorization claim in the query string. A high-entropy opaque token is enough to locate the digest record.
Do not consume a token on the first GET. Mail security scanners and link prefetchers can visit a URL before a person does. Show a recovery page on GET, then consume the token when the user submits a new password. Enforce purpose and expiry at that point, and revoke sessions according to the application's account-security policy. Consider the full sequence: the outbox worker renders a message, the transport accepts it, a mailbox scanner opens the link, and the person follows it several minutes later. If GET consumes the credential, the scanner wins and the person sees an expired-looking recovery flow even though transport did its job. If GET changes nothing, both visits can render the form, but only a valid POST can attempt redemption. Two nearly simultaneous POST requests then meet the atomic database condition; one changes the password and marks the record used, while the other gets the same generic invalid-or-expired result used for any failed credential. The event stream should preserve request, outbox, delivery, and redemption correlation without preserving the secret itself. This one scenario crosses browser behavior, mail security, queue semantics, database concurrency, user messaging, and logging — which is why the token lifecycle cannot be delegated to a template or delivery callback.
Scanner clicks happen.
Template contracts deserve tests. A password-reset template needs the reset URL, expiry wording that matches server policy, and a support route that does not leak account state. Unknown variables should fail rendering in CI. A missing reset_url is a build failure, not a blank link in production.
Retries need identity. A worker replay after a timeout should reuse the outbox item's idempotency key and credential record. Minting another token for every retry leaves several live links in a mailbox and makes incident review difficult. A retry that has no durable record to reference should stop and raise an operational alert instead of silently creating a new credential.
Don't improvise here.
Here is the critical path as a provider-neutral Python contract. A Node.js service can preserve the same boundaries with its transaction, queue, and crypto libraries; the example intentionally does not invent a vendor-specific API method.
from dataclasses import dataclass
from datetime import datetime, timedelta, timezone
from hashlib import sha256
from secrets import token_urlsafe
from typing import Mapping, Protocol
from urllib.parse import urlencode
class ResetStore(Protocol):
def create(self, *, user_id: str, digest: str, expires_at: datetime,
idempotency_key: str) -> None: ...
class MailTransport(Protocol):
def send(self, *, recipient: str, template_version: str,
variables: Mapping[str, str], idempotency_key: str) -> None: ...
@dataclass(frozen=True)
class ResetCommand:
user_id: str
recipient: str
request_id: str
def issue_reset(command: ResetCommand, store: ResetStore,
mail: MailTransport, reset_origin: str) -> None:
raw_token = token_urlsafe(32)
digest = sha256(raw_token.encode("utf-8")).hexdigest()
expires_at = datetime.now(timezone.utc) + timedelta(minutes=20)
store.create(
user_id=command.user_id,
digest=digest,
expires_at=expires_at,
idempotency_key=command.request_id,
)
query = urlencode({"token": raw_token})
reset_url = f"{reset_origin}/account/recover?{query}"
mail.send(
recipient=command.recipient,
template_version="password-reset-v3",
variables={"reset_url": reset_url},
idempotency_key=command.request_id,
)
Twenty minutes is an example policy value, not a universal best practice. Use a fake clock to test the exact expiry boundary, and make the visible template copy agree with the server. In a real implementation, the store and send operation are coordinated through an outbox transaction; the simplified function shows the contract, not a claim that two independent calls are atomic.
What do custom-domain SPF, DKIM, and DMARC actually guarantee?
Custom-domain setup is a chain of identities, not a single checkbox. SPF authorizes sending infrastructure for a domain. DKIM signs the message with a domain key. DMARC evaluates SPF and DKIM results, checks identifier alignment with the visible From domain, and publishes policy and reporting instructions through DNS. RFC 7489 defines those evaluation and reporting mechanisms.
Verify the exact From domain, DKIM signing domain, and return-path behavior in every environment. A staging sender that shares production identity can pollute reputation and make aggregate reports hard to interpret. Keep a canary message in the promotion gate: confirm the link's hostname, template version, and authentication results before sending real recovery traffic.
Authentication does not solve content or reputation problems. Sudden volume, complaint spikes, malformed MIME, and a broken unsubscribe policy for non-transactional mail can still affect placement. Record provider events as normalized internal events such as accepted, delivered, delayed, bounced, or complained. Alert on distribution changes, not just on a successful API response.
Which delivery boundary should the architecture choose?
The options differ mainly in control and operational load. None transfers ownership of reset validity away from the application.
| Boundary | Application owns | Delivery layer owns | Appropriate when | Trade-off |
|---|---|---|---|---|
| Transactional email API | Token lifecycle, outbox, templates, redemption | Acceptance, transport, delivery events | The team wants a narrow HTTP integration | Provider quotas and webhook semantics need an adapter |
| SMTP relay | Token lifecycle, queue, MIME, redemption | Relay and onward transport | An organization already operates mail infrastructure | More connection, bounce, and reputation work stays in-house |
| Self-hosted transfer | The complete recovery and mail pipeline | Nothing outside the team | Direct infrastructure control is mandatory | Highest on-call and deliverability burden |
The catch is dependency concentration in the API option: quotas, regional processing, event retention, and incident support become evaluation criteria. It is not suitable when policy requires direct control of mail-transfer infrastructure or an established internal relay is audited and reliable. Stick with that relay when its reputation, bounce handling, and audit controls are already operated well.
Cost belongs after deliverability controls, data handling, regional fit, event quality, and on-call ergonomics. Compare billing against realistic notification and retry volume only after those gates pass. The least expensive request is not useful if the team cannot explain a delivery gap during account recovery.
Rejected option and its valid use case
I reject synchronous send-on-request for the primary web path. It couples user latency to DNS, transport, rate limits, and template rendering. A browser timeout can happen after a message was accepted, causing a second request and an ambiguous retry. The outbox gives one durable intent and one place to apply idempotency.
Synchronous delivery still fits a controlled integration test or an internal tool where the caller explicitly needs a transport result and account enumeration is not a concern. Even there, credential creation and redemption remain application-owned. A fake transport can capture the rendered message, assert the custom domain and template variables, and hand the token to the test without touching a real inbox.
I also reject using SMS WebOTP as a transparent substitute for an email reset link. MDN describes WebOTP as a browser API for receiving a specially formatted one-time password from an SMS message, with user consent in a secure context. It can support an SMS verification flow, but it changes channel, browser support, consent, and abuse assumptions. Make that a separate decision.
The acceptance record is short: neutral responses, single-use application state, validated reset origin, versioned templates, aligned SPF/DKIM results evaluated through DMARC, idempotent outbox delivery, normalized events, and race-tested redemption. Those checks matter more than a feature matrix.
References
- RFC 7489: Domain-based Message Authentication, Reporting, and Conformance (DMARC): https://datatracker.ietf.org/doc/html/rfc7489
- MDN Web Docs: WebOTP API: https://developer.mozilla.org/en-US/docs/Web/API/WebOTP_API
Top comments (0)