ApexZ69

Posted on Oct 9

Password Reset Email Deliverability Explained: Custom Domain Setup Through Template Ownership

#email #observability #security

Short answer: the best password-reset email setup is the one in which your team owns the message contract, your sending system owns authentication and delivery, and neither side can silently change the other. For a marketplace seller, keep reset-token creation and template meaning in the application; give the delivery layer rendered content plus stable metadata; authenticate a custom sending domain with DKIM; and feed bounces and suppressions back into your own account state and telemetry. Apply the same contract in the US and EU, while keeping region routing and data handling explicit.

That boundary matters more than a long feature checklist.

A reset email is a security transaction. It may also be the only route back to the dashboard where a seller sees a new order. Treat its template, delivery evidence, and failure policy as production code.

The before-and-after mental model

The fragile version sounds convenient: an application asks a provider to send template reset-v4, and the provider dashboard contains the subject, HTML, variables, and active revision. Product copy lives outside review. A dashboard edit can alter the message without an application deployment. Logs may say that reset-v4 was accepted, but they do not prove which wording the seller received.

The cleaner version is a small chain with named owners. Picture it left to right: account service -> reviewed template -> delivery adapter -> mailbox provider -> delivery events. Then draw a return arrow from bounce or suppression events to an internal event consumer. That is the whole operational diagram.

In this model, the account service owns token purpose, expiry, recipient, locale, and request correlation. The repository owns subject and body revisions. The adapter owns the translation into a provider request. The sending service owns queueing and delivery attempts. Your event consumer owns the durable interpretation of results.

This split gives you a useful deployment property. Copy and code that rely on each other ship together. Authentication records and delivery mechanics can change independently, as long as the adapter contract stays stable.

Who should own the reset template?

Start with the change that carries the greater risk. A provider-managed template can be reasonable when a non-engineering team must edit campaigns frequently. Password recovery is different: a changed link variable, accidental personalization field, or ambiguous subject can break a security flow. Repository ownership usually wins because review, testing, rollback, and localization keys travel with the code that creates the reset request.

There is a trade-off. Repository ownership makes copy changes wait for the software delivery path. That is deliberate friction, not free convenience. If your organization needs an editor, build approval around a versioned source file and publish an immutable artifact. Do not let the editor become a second source of truth.

The contract should also avoid provider vocabulary. templateId looks harmless, but it leaks dashboard state into domain code. Prefer a message such as password-reset-requested with a schema version. The adapter may map that version to rendered HTML or to an immutable remote revision. The application should not care which transport performs the final send.

Here is a minimal boundary. It keeps the token out of logs, records a content revision, and gives every attempt a correlation key.

type PasswordResetMessage = {
  kind: "password-reset-requested";
  schemaVersion: 1;
  recipient: string;
  locale: "en-US" | "en-GB";
  resetUrl: string;
  templateRevision: string;
  requestId: string;
  region: "us" | "eu";
};

type DeliveryReceipt = {
  requestId: string;
  transportMessageId: string;
  acceptedAt: string;
};

interface TransactionalEmailPort {
  sendPasswordReset(message: PasswordResetMessage): Promise<DeliveryReceipt>;
}

async function sendSellerReset(
  port: TransactionalEmailPort,
  message: PasswordResetMessage,
): Promise<DeliveryReceipt> {
  if (!message.resetUrl.startsWith("https://")) {
    throw new Error("Reset URL must use HTTPS");
  }

  return port.sendPasswordReset(message);
}

Acceptance is not delivery.

The receipt means the delivery layer accepted the request. It does not mean the inbox accepted it, the seller saw it, or the link was used. Keep those states separate. This is where crisp telemetry beats hopeful naming.

How should a custom domain password reset email setup protect deliverability?

Use a custom sending domain that your organization controls, and publish the authentication records required by your sending arrangement. Google’s sender guidance requires all senders to Gmail accounts to use SPF or DKIM; it places additional SPF, DKIM, and DMARC requirements on senders above its bulk threshold. The practical lesson is broader than one mailbox: authentication is a deployment dependency. Verify it before enabling traffic, and monitor it after DNS or provider changes.

DKIM proves that a message was signed for a domain and was not altered in transit in a way that breaks the signature. It does not prove that your reset workflow is correct. Log the selector and signing domain as deployment metadata, but never log reset URLs or tokens.

Suppression needs a similarly explicit owner. The transport may maintain its own suppression list, yet the application still needs a normalized outcome such as permanent_failure, temporary_failure, or suppressed. Otherwise a seller can request five resets, receive none, and leave the support team with five unrelated provider identifiers. The concrete debugging path should stay intact: support starts with the seller's reset request, finds its internal request ID, sees the template revision and selected region, follows the mapped transport ID, and reads the normalized terminal outcome. If an event arrives twice, the consumer recognizes the same event rather than counting a second failure. If events arrive out of order, the state transition rules prevent an older temporary result from replacing a later terminal result. Store the request ID, template revision, region, event category, and timestamps. Hash or otherwise minimize recipient data in general-purpose logs according to your privacy design.

Do not retry every failure. A temporary failure may justify bounded retry inside the delivery layer. A permanent recipient failure should stop automatic attempts until the address changes or policy permits another attempt. A suppression response should be visible to support without exposing the reset secret. Exact event names differ by transport, so normalize at the adapter and preserve the raw event in restricted storage only when your retention policy calls for it.

Watch four separate signals: requests created, requests accepted by the transport, terminal delivery outcomes, and resets completed. The gaps tell different stories. Created minus accepted points toward your integration. Accepted minus delivered points toward transport or mailbox handling. Delivered minus completed is not automatically a delivery problem; the seller may have ignored the message or started another reset.

How do US and EU paths stay consistent?

Use the same message schema and template revision in both regions. Route at the adapter boundary, and include the selected region in the receipt and event record. This prevents regional infrastructure from turning into regional product behavior.

Data location is a separate decision from deliverability. Document which fields cross a regional boundary, which system stores event payloads, and how long each copy remains. A vague promise that a provider is “global” cannot answer those questions.

Your architecture record can.

Deploy the template before code begins emitting its new schema version. During rollout, keep the previous renderer available until outstanding jobs have drained. Test both region routes with controlled accounts, then compare the four signals above by region and template revision. No secret values belong in the comparison.

What about SMS fallback and provider selection?

SMS can be a recovery fallback, but it is a different channel contract. Twilio’s technical overview notes that GSM-7 messages have a 160-character limit, while UCS-2 messages have a 70-character limit, and concatenation changes the per-segment capacity. A localized character can therefore change segmentation. Keep SMS copy separately versioned and test its encoding; do not mechanically strip the email template into a text message.

For an API provider, ask for evidence rather than a brand promise. Can you use a domain you control and inspect the DKIM setup? Can you export suppression and bounce events with stable identifiers? Can you route US and EU traffic without changing application semantics? Can you replay events idempotently? Can you pin or record the template revision that produced a message? Finally, can support trace one seller request from creation to terminal outcome without seeing the token?

Run that evaluation with one fixture: a marketplace seller requests a reset while a new order is waiting. Exercise accepted delivery, a temporary failure, a permanent failure, a suppressed recipient, a duplicate event, and an out-of-order event. The winning setup is the one whose state remains explainable after all six cases. Price can break a tie later; it cannot repair an untraceable security message.

Template ownership is the anchor. Once the source, revision, and schema have a clear home, authentication becomes testable, provider adapters stay replaceable, and bounce handling becomes an operational workflow instead of a mailbox mystery.

DEV Community