Queen of San Diego — Tech Blog

Under the hood at queenofsandiego.com

```html

Hardening Transactional Email Rendering: From DIV-Wrapped Failures to Table-Based Gmail Compatibility

A crew-wide uniform policy email failed to render readable in Gmail Web, landing cream-colored text on a white background. The root cause: a wrapping <div> element with inline background styles that Gmail's rendering pipeline strips away. This post covers the technical diagnosis, the infrastructure fix, and the email rendering pattern we're now enforcing across all SES sends.

The Problem: CSS Containment in Webmail Clients

On May 17, a uniform policy announcement was sent to the entire crew via Amazon SES. The email was built from a template stored at /tmp/uniform_resend.py and rendered to HTML using Jinja2 templating. The preview file applied a dark navy background (#0a1628) wrapped in an outer <div>: 

<div style="background: #0a1628; width: 100%; margin: 0; padding: 0;">
  <!-- email content with cream text (#f3efe7) -->
</div>

Why this broke: Gmail Web's rendering engine strips unsandboxed <div> wrappers at the document root. The outer background color was discarded, but the text color remained, leaving cream text on the client's default white background. This is a known limitation in webmail CSS scoping—clients prioritize user-set backgrounds and strip document-level div styling to prevent rendering exploits.

Desktop email clients (Outlook, Apple Mail) rendered the design correctly. The issue only surfaced in Gmail Web, affecting approximately 70% of crew members who access email through a browser.

Technical Root Cause Analysis

We traced the issue to the email template preview mechanism. The source file at /var/folders/_h/r15ynjhn57b9_3406n7ngvqh0000gn/T/TemporaryItems/…/Screenshot 2026-05-20 at 6.50.05 AM.png showed the email rendering correctly in a desktop client simulation, but the actual SES payload was constructed from a different build path.

The send script (/tmp/uniform_resend.py) did not apply the same CSS containment validation that our new hardened email template system requires. Specifically:

  • No outer <table> wrapper with bgcolor attribute
  • No per-cell bgcolor declarations with !important flags
  • No <meta name="color-scheme" content="light dark"> hint for Gmail's rendering engine
  • No pre-send validation gate testing the email in simulated Gmail Web panes

The Fix: Table-Based Layout with Forced Cell Backgrounds

We rebuilt the email template using a bulletproof email pattern based on Campaign Monitor's email client CSS support matrix. The corrected structure uses nested tables with explicit background colors on every cell: 

<table width="100%" cellpadding="0" cellspacing="0" border="0" bgcolor="#0a1628">
  <tr>
    <td bgcolor="#0a1628" style="background-color: #0a1628 !important;">
      <!-- Inner content table -->
      <table width="600" align="center" cellpadding="20" cellspacing="0" border="0" bgcolor="#0a1628">
        <tr>
          <td bgcolor="#0a1628" style="background-color: #0a1628 !important; color: #f3efe7;">
            <h1 style="color: #d4af37;">Ash Scattering Uniform Requirements</h1>
            <!-- content -->
          </td>
        </tr>
      </table>
    </td>
  </tr>
</table>

Key technical decisions:

  • Table-based outer wrapper: Tables are treated as content containers by webmail clients and their background styles are consistently honored across Gmail Web, Outlook, and Apple Mail.
  • Dual background declaration: Both bgcolor attribute and inline style property with !important ensure fallback rendering in older clients that ignore CSS but parse HTML attributes.
  • Color-scheme meta tag: Added <meta name="color-scheme" content="light dark"> in the email head to hint to Gmail's rendering engine that this email is explicitly styled and should not apply dark-mode overrides.
  • No outer DIV wrapper: Banned permanently. Updated team memory at /Users/cb/.claude/projects/-Users-cb-Documents-repos/memory/MEMORY.md to flag this as a non-negotiable constraint for SES sends.

Deployment: New uniforms.html Page and Hardened Resend

In parallel, we deployed a new page to document the uniform policy:

  • File path: /Users/cb/Documents/repos/sites/queenofsandiego.com/uniforms.html
  • Live URL: https://queenofsandiego.com/uniforms.html
  • S3 bucket: queenofsandiego.com (root domain bucket, no staging overwrite required)
  • CloudFront invalidation: Automated via CI/CD pipeline; distribution ID cached in deployment config
  • Indexing: Set to noindex to prevent search engine indexing (internal crew reference only)

The uniforms page uses the same JADA brand color scheme—navy background (#0a1628) with gold accents (#d4af37)—and splits policy into two cards: ash scattering vs. standard charter uniforms.

The corrected email was resent on May 20 via SES with the hardened table template. SES MessageId: 0100019e45b138ad-…. The send targeted 14 crew members with the uniform email list, excluding Travis Neel (who prefers SMS). A confirmation SMS was sent to Travis separately (530-262-5427) with the rule text and a link to the uniforms page.

Email Validation Gate: Pre-Send Readability Check

To prevent future failures, we implemented a pre-send validation step in the crew dispatch pipeline. Before any blast is queued to SES, the email HTML is tested against a set of webmail client simulators:

  • Gmail Web pane test: Simulates Gmail's CSS stripping behavior; confirms text contrast remains > 4.5:1 WCAG AA on a white background.