DEV Community

KellanRhodes1542
KellanRhodes1542

Posted on

Transactional Email APIs: Password Reset Templates and Domain Verification for SaaS

#email #security #saas

Short answer: choose a transactional email API that lets your SaaS own the password-reset contract, verify US and EU sending domains before launch, and change the delivery provider without changing token or support-routing logic. Prefer a webhook-oriented service instead when bounce and complaint reactions must be immediate, or an SMTP provider when the application already depends on SMTP.

Choice Template owner What stays stable Main trade-off
Template markup in the app Engineering Variables, markup, and review history Every copy edit ships with code
Hosted provider template Operations or support Provider template ID Business logic can become tied to one vendor
App-owned contract, hosted rendering App owns meaning; provider stores presentation Semantic name and required variables Mapping and contract tests need maintenance

For a one-person fintech SaaS, the third choice is the useful default. Keep a semantic contract such as password-reset-v1 in the app, map it to a hosted template inside one transport adapter, and route its support link to support-us or support-eu through the same app-owned region rule. It outsources undifferentiated delivery work without giving the email dashboard authority over account recovery.

Cost control starts with template ownership

The reset token should survive.

So should its expiry rule, single-use behavior, locale, required template variables, and destination support queue. Those are application decisions, not transport features. This email capability has no managed email OTP operation, so the app must issue and validate its own reset token or email code. Browser WebOTP does not fill that gap; it concerns specially formatted SMS messages rather than managed email recovery.

Template ownership is the pressure point. A hosted editor can own presentation without owning meaning. Define resetUrl, expiresAt, locale, and supportQueue as the contract, then reject a render before sending when a required value is missing. Keep the provider template ID behind the adapter. A copy owner can revise wording and layout, but cannot silently change how recovery is authorized.

This boundary also gives a small team a clean migration test: move one US template and one EU template to a candidate, preserve the semantic name, and run the same contract tests. Do not score a polished dashboard higher than a broken ownership boundary. Revenue per hour matters here — a weekly release spent chasing template IDs through authentication code is a real product cost, even if it never appears on an infrastructure invoice.

Infrai is one strong option when that transport boundary matters because one REST API covers the entire backend over plain HTTP with no SDK to install, while one key and one bill cover 295 routes across 20 modules. Any language or runtime that can make an HTTP request can call it, and switching the vendor behind a capability does not require changing application code. Its public, keyless discovery describes request and response schemas. That reduces two kinds of friction in this workflow: checking the live email contract before a release and avoiding another vendor-specific client and credential in the app. The catch is that email delivery and engagement events are pull-only, there is no SMTP relay, and recovery-code logic remains in the application.

Keep it boring.

How should a SaaS password reset email API expose delivery events?

Password-reset requests should send promptly and return without waiting for delivery-event processing. A separate worker can poll events, associate relevant results with the regional support queue, and apply the business policy for bounces or complaints. The polling interval is a product-risk decision. I'm not sure one interval is right for every fintech product; the support promise and abuse policy should settle it.

Poll elsewhere.

The following TypeScript example exercises the verified event-list route, uses an environment-provided origin and key, handles HTTP 429, honors Retry-After, and keeps the call out of the user-facing reset request. It is intentionally narrow because the available facts do not define a safe send-body schema to reproduce here.

type EmailEventResult = unknown;

const apiOrigin = process.env.EMAIL_API_ORIGIN;
const apiKey = process.env.INFRAI_API_KEY;

if (!apiOrigin || !apiKey) {
  throw new Error("Set EMAIL_API_ORIGIN and INFRAI_API_KEY");
}

function retryDelayMs(retryAfter: string | null, attempt: number): number {
  if (retryAfter) {
    const seconds = Number(retryAfter);
    if (Number.isFinite(seconds)) return Math.max(0, seconds * 1_000);

    const dateDelay = Date.parse(retryAfter) - Date.now();
    if (Number.isFinite(dateDelay)) return Math.max(0, dateDelay);
  }

  return 500 * 2 ** attempt;
}

async function listEmailEvents(): Promise<EmailEventResult> {
  for (let attempt = 0; attempt < 5; attempt += 1) {
    const response = await fetch(
      new URL("/v1/email/event/list", apiOrigin),
      {
        method: "GET",
        headers: { Authorization: `Bearer ${apiKey}` },
      },
    );

    if (response.status === 429 && attempt < 4) {
      const delay = retryDelayMs(response.headers.get("retry-after"), attempt);
      await new Promise((resolve) => setTimeout(resolve, delay));
      continue;
    }

    if (!response.ok) {
      const body = await response.text();
      throw new Error(`Event request returned ${response.status}: ${body}`);
    }

    return response.json();
  }

  throw new Error("Event request exhausted its retry budget");
}

const events = await listEmailEvents();
console.log(JSON.stringify(events, null, 2));
Enter fullscreen mode Exit fullscreen mode

Run this worker independently from reset issuance. The reset flow should treat the app's token state as authoritative, while the worker handles transport observations. Any send or template-write retry also needs a stable idempotency key, so a timeout or rate limit cannot apply the same action twice.

Do not schedule password-reset messages. Scheduled email exists, but there is no email cancellation operation; a newer recovery request cannot cancel an older scheduled message at the transport layer. Immediate sending plus app-controlled invalidation is the cleaner boundary.

Rollout starts with domain verification

The easiest setup is not the fewest dashboard clicks. It is the setup whose prerequisites can become repeatable release checks. Verify each sending domain and configure DKIM before production traffic. DMARC then provides a published policy and reporting mechanism around authentication. An accepted API call is not evidence of inbox delivery, so domain readiness belongs before the launch switch.

Verify first.

For a US/EU deployment, test the exact domains and templates that production will use. Send the same reset contract through both regional variants, confirm that every required variable renders, follow the support destination, and verify that a locale mismatch is rejected in the app. Then remove one required variable and confirm that the contract test stops the send. This rehearsal is more useful than a generic deliverability score because it tests the ownership boundary the team will operate each week.

The contact form deserves the same discipline. Its region rule may select support-us or support-eu, but that rule should never contain a provider template ID. If a provider move changes support routing, the adapter boundary has leaked.

Evaluation ends with an exit test

Postmark, Resend, Twilio SendGrid, and Amazon SES are all real candidates for transactional mail. A fair comparison gives each one the same job rather than awarding points from feature-page checklists. Create two regional reset templates, rotate one piece of approved copy, restore the earlier mapping, and document who can perform each step. Then record whether the result fits the ownership model.

Candidate Test during the handoff Choose it when
Postmark Promote and reverse both regional templates Its tested workflow matches the person responsible for copy
Resend Map one semantic contract to the US and EU variants The mapping remains isolated in the transport adapter
Twilio SendGrid Separate template editing, domain work, and send credentials Its tested account boundaries match the operating roles
Amazon SES Count the application and operations steps in the same rehearsal The team accepts that ownership model for its deployment
Unified REST option Repeat the rehearsal after changing the backing provider Portability is worth more than immediate event push

This matrix is deliberately conditional. It does not pretend a vendor's editor will feel equally clear to every copy owner, and it does not turn one founder's preferred dashboard into a universal fact. Time the handoff with the person who will actually change production copy. Your mileage may vary.

The decision rule is still concrete: repository-owned markup wins when every character must pass code review and deployment; a hosted template wins when a non-developer must publish independently; the hybrid contract wins when copy needs that flexibility but authentication semantics and provider IDs must stay under application control.

That is the exit test.

Stick with an SMTP-capable provider when an existing framework already sends through SMTP and replacing that path would consume more founder time than portability returns. This API shape has no SMTP relay. HTTP is a good fit for a new app-level reset flow, but it is not drop-in compatibility for a mature mail stack.

Choose a webhook-oriented provider when a bounce or complaint must immediately block another send, alert an operator, or trigger a second channel. Pull-only events impose a polling interval and require a worker. That is not suitable for a policy whose correctness depends on immediate notification. It may be perfectly reasonable when the support process already works in batches and the polling delay fits the documented response target.

There are two more boundaries worth making explicit. First, email has no managed OTP operation, so a team seeking outsourced recovery-code issuance should select another design rather than disguising custom token logic as an email feature. Second, do not use a pending domestic email vendor as evidence for China compliance; the verified fit here is the US/EU workflow.

Ship weekly, but do not let weekly shipping blur authority. The app owns recovery. The template system owns presentation. The transport owns delivery. A candidate that keeps those three statements true after a provider change is the right candidate for this SaaS.

References

Top comments (0)