Skip to main content

All Guides

Browse all deep-dive implementation guides in one place.

How the four subject areas fit together Markup and templating produce the message, testing verifies it, and delivery infrastructure carries it to the inbox and returns events. Where Each Area Sits in a Message's Life HTML & CSS what renders in each client engine Templating engines how that markup gets generated per recipient Testing & QA proof it still renders before it ships Delivery authentication, ESPs, events Delivery events flow back the other way: a bounce or complaint changes who you send to, and a spam score regression sends you back to the markup and the templates that produced it. Most production problems cross two of these areas, which is why the guides link across them rather than staying in one lane.
The four areas run in sequence for any single message, and the feedback from delivery loops back into the first two.
Published guides per subject area A bar chart counting the implementation guides currently published under each of the four subject areas. Guides Published in Each Area Counted from the published pages at build time — 56 guides in total Mastering Email HTML & CSS 17 Modern Email Templating... 11 Email Testing & QA Workflows 12 Transactional Email Delivery... 16 Depth follows demand: the areas with the most client-specific failure modes carry the most guides.
Guide counts per area, computed from the published pages themselves rather than maintained by hand.
Where to start reading Four entry points chosen by symptom: broken rendering, unmaintainable templates, regressions reaching production, or mail not arriving. Start From the Symptom You Have "It looks wrong in one client" start with the HTML & CSS guides engine quirks, VML, dark mode, layout "Our templates are unmaintainable" start with the templating engines components, data binding, migrations "Regressions reach production" start with testing & QA workflows snapshots, visual diffs, client farms "Mail is not arriving at all" start with delivery infrastructure authentication, bounces, webhooks
The fastest route in is usually the symptom, not the subject — each entry point leads into the guides that address it.

Automating Litmus Spam Testing in CI

Gate deploys on spam-filter and authentication checks by submitting emails to the Litmus API, polling SpamAssassin and SPF/DKIM/DMARC results, and failing on regressions.

Building a Custom MJML Component

Write an MJML component that compiles to correct table markup: allowed attributes, the render method, where it may sit in the tree, and registering it in the build.

Building a Type Scale for Transactional Emails

Design a five-step email type scale in absolute units: paired sizes and leading, a 14px floor, mobile steps, and why fewer steps render more consistently.

Building an Idempotent Webhook Consumer for Email Events

Build an idempotent email webhook consumer: dedupe on the provider event id, make side effects safe to repeat, and resolve out-of-order events deterministically.

Catching HTML Size Regressions Before Gmail Clips the Message

Gate on message weight: where the 102KB Gmail clipping threshold applies, measuring after inlining, per-template budgets, and attributing a size jump to its cause.

Centering Buttons Across Outlook and Gmail

Center a call-to-action reliably: why margin auto fails in the Word engine, the align attribute plus text-align pair, and centering a fixed-width VML button.

Configuring a DMARC Policy: Moving Safely from p=none to p=reject

Stage a DMARC rollout on a live transactional domain: p=none monitoring, pct-ramped quarantine, then reject, with exact DNS records and aggregate-report reading.

Configuring the Litmus API in GitHub Actions for Automated Email QA

Configure the Litmus API as a GitHub Actions step for automated email rendering checks on every pull request.

Converting HTML Emails to MJML Components: Implementation Workflow

Step-by-step workflow to migrate legacy HTML email templates to MJML components with rendering validation and automated testing.

Creating Rounded Buttons in Outlook with VML roundrect

Fix square email buttons in Outlook 2007-2021 with v:roundrect, arcsize, fillcolor, and w:anchorlock wrapped in MSO conditionals and hidden from other clients.

Designing a Dead-Letter Queue for Failed Transactional Sends

Give failed email sends a terminal state: what belongs in a dead-letter queue, the payload it must retain, alerting on any arrival, and a safe replay path.

Fixing Dark-Mode Logo Inversion in Outlook and Apple Mail

Stop Outlook.com and Apple Mail dark mode from inverting your dark logo into an unreadable shape, using picture media queries, data-ogsc selectors, and background plates.

Fixing Gmail App Media-Query Stripping on Android and iOS

Build a fluid hybrid email layout that stays responsive in the Gmail app when @media and style blocks are stripped for non-Gmail accounts on Android and iOS.

Fixing Line-Height Inconsistencies in Outlook 2016-2021

Stop the Word engine recomputing leading from font metrics: absolute line-height, mso-line-height-rule exactly, and the elements that need it beyond paragraphs.

Fixing SPF PermError: Too Many DNS Lookups (10-Lookup Limit)

Resolve SPF PermError caused by exceeding the RFC 7208 ten-DNS-lookup limit: count lookups, flatten or consolidate includes, and add CI checks, with before/after records.

Full-Width Background Images in Outlook with VML

Make edge-to-edge background images span the full body width in Outlook 2007-2021 using v:rect, mso-width-percent, v:fill type=frame, and v:textbox.

Handling Hard Bounces with Amazon SES and SNS

Configure an SES configuration set, SNS topic, and HTTPS/Lambda subscriber to parse bounce JSON, suppress Permanent recipients, and stay under SES bounce-rate thresholds.

How to Fix Outlook Table Spacing Issues

Fix Outlook table spacing issues caused by mso-table-lspace, cellspacing, and Word engine quirks in HTML email templates.

Implementing a WCAG Compliance Checklist for Transactional Emails

Actionable WCAG 2.2 compliance checklist for transactional email HTML—aria labels, color contrast, and semantic structure guidelines.

Implementing Dynamic Liquid Tags for Transactional Emails: API Integration & Debugging Guide

Implement dynamic Liquid template tags for Shopify transactional emails with API integration and step-by-step debugging techniques.

Implementing Jest Snapshot Testing for MJML Templates

Step-by-step guide to configuring Jest snapshot tests for MJML email templates in Node.js projects with CI/CD integration.

Inlining CSS in a Python Pipeline With Premailer

Wire an inliner into a Python send path: keeping media queries, preserving MSO conditionals, caching the parse, and asserting the output before dispatch.

Mapping Figma Variables to Email Design Tokens

Sync a design tool's variables into an email token set: name mapping, the properties email cannot express, light/dark modes, and a review step that catches drift.

Migrating from Handlebars to Jinja2 in Python Email Pipelines

Migrate transactional email templates from Node/Handlebars to Python/Jinja2: syntax mapping, autoescaping differences, whitespace control, and inliner integration.

Migrating from SendGrid to Amazon SES Without Hurting Deliverability

A phased plan to move transactional email from SendGrid to Amazon SES: domain verification, IP warm-up, suppression port, and SNS webhooks, with no deliverability hit.

MJML vs React Email for Transactional Systems

Compare MJML and React Email for transactional templates: type safety, data binding, output HTML quality, ecosystem, and where each component model wins.

Monitoring Gmail Postmaster Tools for Spam Rate Regressions

Pull Gmail's user-reported spam rate through the Postmaster Tools API, alert on absolute and relative thresholds, and attribute a spike to the stream that caused it.

Preserving Media Queries When Inlining CSS with Juice

Stop Juice from flattening or dropping @media and prefers-color-scheme rules so your responsive and dark-mode email styles survive the inline step.

Preventing Duplicate Transactional Sends With Idempotency Keys

Stop duplicate receipts and double password resets: derive stable idempotency keys from business events, understand provider key windows, and add a local guard.

Preventing Font-Size Inflation in iOS Mail and the Gmail Android App

Stop mobile clients enlarging small text per block: text-size-adjust on iOS, the 14px floor that avoids Android inflation, and why one paragraph grows and its neighbour does not.

Previewing Emails Locally with MailDev in Docker

Run MailDev as a Docker SMTP sink to capture outbound mail in local development, point Nodemailer, Django, or Rails at it, and inspect messages in a browser UI.

Processing Feedback Loops and Spam Complaints

Subscribe to SES, SendGrid, and Postmark complaint notifications, parse ARF reports, suppress complainers instantly, and enroll in Yahoo CFL and Microsoft JMRP feedback loops.

Publishing Email Design Tokens as an npm Package

Ship email tokens as a versioned package: one source of truth, generated outputs for JSX and markup engines, export maps, and a release process that cannot drift.

Rate Limiting Transactional Sends With a Token Bucket

Implement a distributed token bucket in Redis for ESP rate limits: burst capacity, atomic refill, per-provider buckets, and why a fixed window causes 429 storms.

Reading a SpamAssassin Report Rule by Rule

Turn a spam score into a fix list: rule categories, the hits worth acting on, negative-score rules, and why the largest number is usually not the one to chase.

Reducing Spam Score in Image-Heavy Emails

Fix the image-to-text ratio rules: real text instead of baked-in copy, alt text that is not a substitute, image hosting signals, and the blocked-images fallback.

Removing Auto-Linked Blue Text in Outlook and iOS Mail

Stop clients auto-linking phone numbers, dates and addresses into blue underlined text: the x-apple-data-detectors override, MSO link colour, and the wrapper technique.

Removing Your Sending IP From a Blocklist Without Getting Relisted

Diagnose why a sending IP or domain was listed, stop the traffic, remediate the actual cause, and request delisting with the evidence operators require.

Replaying Missed Webhook Events From an ESP

Recover from a webhook outage: detect the gap, pull the missing window from the provider's API, replay through the same idempotent consumer, and verify the state converged.

Retina Background Images in Email Without Doubling the Weight

Serve a 2x background that stays sharp on high-density screens: sizing rules, the VML path for Outlook, compression that offsets the pixel count, and the fallback colour.

Rotating DKIM Keys Without Downtime

Roll a DKIM key safely: publish the new selector first, switch signing, wait out in-flight mail and DNS caches, then retire the old selector — with the checks at each step.

Running Local Email Previews with Mailpit

Install and configure Mailpit as a local SMTP server to preview and debug transactional HTML emails directly in your browser.

Sandboxing Jinja2 Templates for Multi-Tenant Email

Let customers edit their own email templates safely: SandboxedEnvironment, attribute allowlists, render timeouts and output size caps, plus the escapes a plain Environment leaves open.

SendGrid vs Postmark vs Amazon SES for Transactional Email

A decision-focused comparison of SendGrid, Postmark, and Amazon SES for transactional email: price, deliverability, webhooks, suppression, and dedicated IPs.

Setting Up a Seed-List Inbox Placement Test

Build a seed panel that reports where transactional mail actually lands: panel composition, fixture data, scheduling, and alerting on change rather than absolute share.

Setting up React Email with Next.js: API Integration & Configuration

Configure React Email in a Next.js project with API route integration, preview server, and transactional email delivery setup.

Stacking Email Columns Without Media Queries

Build columns that reflow from width alone: inline-block with max-width, the ghost table for Outlook, whitespace control, and why this survives clients that strip CSS.

Testing Dark Mode Email Across Clients

Verify dark mode before sending: which clients need separate checks, a fixture that exposes every inversion failure, and the automated contrast pass that catches regressions.

Testing React Email Components With Vitest

Set up Vitest for email components: snapshot the compiled HTML, assert the client workarounds that must survive refactors, and normalise the output that changes per run.

Troubleshooting CSS Media Queries for Mobile Email Clients

Debug CSS media query failures in Gmail, Outlook, and iOS Mail for responsive HTML email layouts on mobile devices.

Verifying SendGrid Event Webhook Signatures (ECDSA)

Verify SendGrid Event Webhook ECDSA signatures in Node.js against the raw request body and timestamp to block forged delivery, bounce, and complaint events.

Versioning Shared Email Components Across Teams

Release email components without shipping surprise visual changes: a stricter semver reading, snapshot gates, deprecation windows, and coordinated upgrades.

Visual Regression Testing of Emails with Playwright

Catch unintended visual changes in rendered HTML emails in CI by screenshotting them in Playwright chromium and webkit and diffing against stored baselines.

Warming a Dedicated IP for Transactional Email Without Losing Placement

Ramp a new dedicated sending IP safely: a volume schedule driven by receiver feedback, recipient selection by engagement, and the hold rules that prevent a stalled warm-up.

Web Font Fallbacks for Apple Mail: Exact Configuration & Debugging Protocol

Configure @font-face fallbacks for Apple Mail and iOS Mail with system font stacks and debugging workflows for email typography.

Writing Alt Text That Works When Images Are Blocked

Alt text in email serves two audiences at once: screen readers and every recipient with images off. Which images need it, what to write, and how to style it so it reads.