Password Reset Email Deliverability for Custom Domain Provider (and Bounce Evidence Limits)

When a user requests a password reset, the system generates a unique single-use token, logs the request details, and sends an email with the reset link. To ensure reliable email delivery and maintain an audit trail, follow these best practices:

1. Use a custom domain with properly configured DKIM and SPF records. This allows the email provider to verify the authenticity of the sender and helps prevent spoofing.

2. Implement a reliable email sending system that supports message IDs, bounce events, and allows for exportable history. This provides the necessary evidence to determine what happened to each email message.

3. Record key information for each email interaction, including:

- A hash of the random token used for the reset link

- Expiry time of the token

- The associated account identifier

- Timestamp of the reset request

4. Create a unique internal message ID at the time of enqueue and store it in provider metadata. Include information such as the From domain, DKIM selector, SPF policy version, template revision, and queue timestamp.

5. Normalize incoming email events into an append-only record, keeping both the raw bounce reason and your versioned classification. The classification determines whether the email should be retried, suppressed, or ignored.

6. Develop a decision function (like the `nextAction` function provided) that processes each email event based on its kind (accepted, delivered, temporary bounce, permanent bounce, or complaint) and returns the appropriate action (retry, suppress, or none).

7. Test your email delivery setup thoroughly in staging and production environments, ensuring that both marketing and account recovery streams are properly authenticated and aligned.

8. Implement proper webhook handling by making the processing idempotent, rejecting duplicate events based on the provider event ID, and writing suppression rows before another reset request can be queued.

9. Hash recipient email addresses in routine logs, but retain a reversible mapping only for support and legal purposes. Separate recovery traffic from promotional traffic to maintain a clear audit trail.

10. Clearly document the purpose of each email stream and restrict access to suppression decisions. Ensure that only authorized personnel can remove suppression and provide a clear record of the decision-making process.

By following these guidelines and maintaining a comprehensive audit trail, you can ensure reliable email delivery for password reset emails while also providing the necessary evidence for audits and investigations.