Clinical Password Reset Proof — Simple API-First Email, No SMTP, Bounded Cost

A healthtech password reset email implementation is constrained by the evidence its API must leave behind: the team needs to show what the application decided, while keeping the short-lived secret out of its logs.

Short answer: use a server-side email API behind a narrow delivery adapter, store a redacted attempt record before dispatch, accept delivery events into an append-only evidence stream, and keep account recovery separate from both the web framework and the mail transport.

No SMTP relay is required in the application. The real selection criterion isn't which API takes the fewest lines of code; it is whether the whole path can preserve a stable correlation ID, authenticate events, explain retries, and enforce the retention policy your compliance owner approves. Cost belongs in the comparison, but after those controls.

Start with the evidence boundary

The reset token is a bearer secret. An audit record should therefore identify the request without reproducing the token, reset URL, or full message body. I would model three separate records: the security decision that authorized a reset, the delivery attempt made by the application, and the later delivery event reported by the communications system. Their shared correlation ID proves sequence without turning the audit store into another credential store.

This separation also fixes a common modeling mistake. A successful API response means the handoff was accepted under whatever contract you selected; it does not, by itself, establish that a person received or opened the message. Name those states precisely. An auditor should not have to infer what success=true meant six months later.

For a concrete policy example, give a reset link a 10-minute expiry, record the configured expiry as 600 seconds, and store only a digest of the recipient identifier. Ten minutes is an application choice here, not a universal security standard. Your threat model may justify less or more.

Keep the evidence payload small:

Small records are easier to govern.

How should Node.js, Express, and Next.js send a password reset email without SMTP?

The framework should call an application service, and that service should call a transport-neutral interface. Express route handlers and Next.js server handlers can both supply the authenticated account context, but neither should construct provider payloads or expose a mail credential to browser code. API-first means the transport crosses an authenticated HTTP boundary; it does not mean the browser calls that boundary directly.

All code here is Python because the architectural contract matters more than framework syntax. The same three methods map cleanly to a Node.js interface.

from dataclasses import dataclass
from datetime import datetime, timezone
from typing import Protocol


@dataclass(frozen=True)
class ResetMessage:
    correlation_id: str
    recipient: str
    reset_url: str
    expires_in_seconds: int
    template_version: str


@dataclass(frozen=True)
class Handoff:
    external_id: str
    accepted_at: datetime


class EmailDelivery(Protocol):
    def send_password_reset(self, message: ResetMessage) -> Handoff:
        ...


class EvidenceStore(Protocol):
    def append(self, record: dict[str, object]) -> None:
        ...

The application writes its attempt evidence before calling send_password_reset, then appends the handoff result. That ordering matters: if the process stops between those actions, the evidence says "attempted, outcome unknown" rather than inventing delivery. A worker can reconcile that state using the idempotency contract of the selected API. If the API cannot define duplicate handling clearly, it is a poor fit for this workflow no matter how attractive its sample code looks.

The adapter owns message rendering, HTTP authentication, timeout policy, response parsing, and the mapping from external events to internal states. The security service owns token creation, one-time consumption, expiry, and account-level rate policy. Don't merge those responsibilities. Mail delivery should never become the authority on whether a reset token is valid.

Evidence has failure modes too

Start with lost intent. If dispatch occurs before the attempt is recorded, a process interruption can produce a message that has no local explanation. Reverse the order and use an outbox or an equivalent durable handoff when the database and delivery API cannot participate in one transaction. The cost is a worker and reconciliation logic; the gain is an explicit state for every authorized request.

Then consider duplicates. Suppose attempt r-017 is recorded at 09:00:00 with a 600-second expiry, the API call begins, and the client times out two seconds later without a response. The evidence state is still outcome_unknown; it is neither rejected nor accepted. A retry may represent a new send or the completion of the old send, and the application cannot decide which from elapsed time alone. Reuse the same idempotency key and correlation_id, preserve both attempt timestamps, and reconcile against the duplicate contract selected during evaluation. If a later authenticated event identifies the original handoff, append that event and close the unknown state without rewriting history. This is where a supposedly simple password reset implementation gets expensive: not in the first API call, but in the states around it.

Unknown is a state.

Event ingestion creates a different trust boundary. Authenticate the event using the mechanism documented by the selected service, reject stale or replayed inputs according to that contract, retain the original event identifier, and make state transitions monotonic. An accepted event arriving after a later terminal event must not move the record backward merely because queues reordered it.

Logs are another leak path. Redact authorization headers, query strings, reset URLs, email bodies, and raw recipient addresses before they reach shared observability systems. A trace may carry the opaque correlation ID. It should not carry the credential.

Finally, sender authentication is related to delivery but not equivalent to application evidence. SPF defines a mechanism for a receiving mail system to check whether a host is authorized to use a domain in the relevant mail identity. That helps establish sending authorization; it does not prove that your user received a reset or that your internal authorization decision was correct. Treat domain authentication checks and application audit checks as separate rollout gates.

I'm not sure there is a defensible universal retention period for these records, because the answer depends on jurisdiction, organizational policy, and the data classification assigned to each field. Resolve that with the compliance owner, document the decision, and test deletion as carefully as insertion.

Compare contracts, then cost

A useful evaluation is a scored contract review, not a feature-count contest. Run the same test fixture against every candidate and preserve its results with the architecture decision record.

The catch is that an HTTP email API is not suitable when policy requires infrastructure you operate entirely inside a controlled network boundary, or when an established relay already supplies the evidence, authentication, and operational ownership you need. Stick with that relay when changing transport would add another trust relationship without improving the audit story. Conversely, a generic SMTP relay is a weak choice when the team needs structured, authenticated lifecycle events and would otherwise have to build and operate that event layer itself.

SMS can be an independent recovery channel if policy permits it, but don't silently reroute a failed email reset to a phone number. That changes the authentication surface, consent context, evidence schema, and abuse controls. Model it as a separate decision path; the Twilio SMS documentation is one example of how SMS has its own API concepts rather than acting as email with a shorter body.

Roll out the proof before the traffic

Begin with contract tests for redaction, expiry, duplicate requests, event replay, reordering, and an ambiguous handoff outcome. Deploy the adapter behind a transport-neutral flag, mirror only non-secret evidence in a staging environment, and have security and compliance reviewers read a reconstructed timeline rather than a dashboard screenshot.

Then canary a narrow account cohort. Watch counts of authorized decisions, queued attempts, known outcomes, and unresolved outcomes by correlation ID; alert on impossible transitions and growing reconciliation age. Rollback should switch the adapter, not alter token semantics or erase the evidence already written.

The final acceptance test is blunt: given one account-recovery request, can an authorized reviewer explain the decision, template version, configured expiry, handoff, subsequent events, retries, and deletion schedule without seeing the token or message body? If not, the implementation isn't ready, even if the email arrives quickly.

References

• https://datatracker.ietf.org/doc/html/rfc7208
• https://www.twilio.com/docs/sms