Email templates are the fastest way to ship consistent transactional email, but they are also one of the easiest places to ship regressions. A small HTML change can break a password reset button, leak the wrong environment link, or fail in dark mode.

This guide focuses on the practical side: how to design templates your team can reuse, and how to test them like code before they reach customers.

What counts as an "email template"?

An email template is a repeatable email body plus a set of variables you fill at send time. In a typical product, templates cover:

  • OTP or verification codes
  • Password resets and magic links
  • Receipts, invoices, and alerts
  • Team notifications and workflow status updates

If your template has any user-impacting link or code, treat it as part of your release surface.

Common failure modes (and how to prevent them)

Before you write more templates, decide how you will prevent these common issues:

  • Broken links: wrong hostname, missing UTM params, or a stale route after refactors
  • Missing variables: shows up literally in production
  • Unsafe HTML: unescaped content breaks the layout or introduces injection risk
  • Rendering drift: looks fine in Gmail, breaks in Outlook, fails in dark mode
  • Spam signals: too many tracking domains, heavy images, or missing authentication

You can catch most of these with a lightweight template test workflow.

Template variables and substitution

MailSlurp templates support variable replacement so one template can serve many user events.

If you're building "merge variables" or handlebars-style placeholders, use the dedicated guide:

The goal is to make template validation deterministic:

  1. Generate an inbox for a test run.
  2. Send the template using a known set of variables.
  3. Assert the HTML contains the right link targets and copy.
  4. Extract codes or links and verify they behave.
  5. Gate the release if the checks fail.

Send a templated email

Create a template once:

Send with runtime variables:

For example, validate that the template produced a working reset URL (and not a staging link).

If your template carries OTP codes, see:

HTML email checklist for release readiness

Use this as a pre-merge checklist for template changes:

  • Subject is descriptive and testable (not "Hello")
  • Text alternative exists or the copy is readable without images
  • Links use the correct environment base URL
  • Buttons are accessible and work without images
  • Variable placeholders have defaults or validation
  • Branding assets are on stable URLs (no expiring signed URLs)
  • Tracking pixels are intentional (and don’t break deliverability)

Next steps