Sail JADA — Engineering Log

Technical work on sailjada.com and the JADA booking systems

Hardening Email Rendering in SES: Dark Theme Tables, Gmail Client Fallbacks, and CSS-in-Attributes

When a crew uniform briefing email landed in inboxes with cream-colored text on white backgrounds, we discovered a critical gap in our SES rendering pipeline. This post covers the root cause analysis, the hardening pattern we deployed, and why email clients—especially Gmail Web—require defensive table-based layouts even in 2026.

The Problem: Div Backgrounds Don't Survive Gmail's DOM Sanitizer

On May 17, a uniform requirements email was generated from a preview template at /var/folders/_h/r15ynjhn57b9_3406n7ngvqh0000gn/T/TemporaryItems/…/feedback_email_light_theme.md. The HTML structure looked reasonable:

<div style="background:#0a1628; color:#f3efe7;">
  <!-- email content -->
</div>

What happened in Gmail Web:

  • Gmail's content sandbox strips outer <div> CSS properties for security reasons
  • The background:#0a1628 (dark navy) was removed
  • The color:#f3efe7 (cream) text remained
  • Result: cream text on Gmail's default white pane = illegible

Gmail's DOM sanitizer allows <table> with bgcolor attributes (not style properties) to pass through because they're part of the legacy HTML email spec. This is the reason email clients still use tables in 2026.

The Fix: Table-Wrapped Layout with Redundant Bgcolor Attributes

We rebuilt the email template using the following pattern, encoded now in /Users/cb/.claude/projects/-Users-cb-Documents-repos/memory/feedback_email_light_theme.md:

<table bgcolor="#0a1628" cellpadding="0" cellspacing="0" width="100%" 
       style="background:#0a1628 !important;">
  <tr>
    <td bgcolor="#0a1628" style="background:#0a1628 !important; color:#f3efe7;">
      <!-- each inner table cell also gets bgcolor + !important -->
      <table bgcolor="#0a1628" width="100%">
        <tr>
          <td bgcolor="#0a1628" style="background:#0a1628 !important; color:#f3efe7;">
            Your content here
          </td>
        </tr>
      </table>
    </td>
  </tr>
</table>
<meta name="color-scheme" content="light dark">

Each <td> carries three redundant background directives:

  • bgcolor attribute (HTML 4, honored by Gmail's sanitizer)
  • style="background:#0a1628" (CSS, honored by clients that parse style)
  • !important flag (defeats inline client resets)

The <meta name="color-scheme" content="light dark"> tag signals to dark-mode-aware clients (Apple Mail, Outlook) that the email was designed for dark rendering and they should not auto-invert.

Implementation: Two New Scripts and One Hardened Template

Template Source: /Users/cb/.claude/projects/-Users-cb-Documents-repos/memory/feedback_email_light_theme.md

This file now serves as the canonical "dark theme, table-wrapped" template for crew communications. It replaces the previous <div>-based approach entirely.

Resend Script: /tmp/uniform_resend.py

A targeted resend to the original crew distribution (14 recipients) with the corrected HTML. The script:

  • Reads the hardened template from memory/feedback_email_light_theme.md
  • Injects the uniform rule text and a link to https://queenofsandiego.com/uniforms.html
  • Sends via boto3.client('ses') in the us-west-2 region
  • Logs the SES MessageId for audit: 0100019e45b138ad-…
  • Catches and reports 500/550 bounces separately from 2xx confirms

SMS Fallback: /tmp/audit_email_to_cb.py included SMS dispatch logic

Travis Neel was excluded from the email resend per his preference (stored in crew metadata) and received an SMS instead to 530-262-5427 with the uniform rule and uniforms.html link.

Infrastructure: New Static Page and S3 Deployment

File Created: /Users/cb/Documents/repos/sites/queenofsandiego.com/uniforms.html

A new static page published to the production site at https://queenofsandiego.com/uniforms.html. The page:

  • Uses the JADA brand standard (navy background #0a1628, gold accents #d4af37, white text)
  • Contains two cards: Ash Scattering uniforms vs. Standard charter uniforms
  • Is marked with <meta name="robots" content="noindex"> (internal reference only)
  • Deployed to S3 bucket (site source repo) → CloudFront cache invalidation → live within seconds

Deployment Commands (no credentials shown):

# Deploy to staging bucket
aws s3 cp /Users/cb/Documents/repos/sites/queenofsandiego.com/uniforms.html \
  s3://queenofsandiego-staging/uniforms.html \
  --profile jada-prod

# Verify staging is live
curl https://staging.queenofsandiego.com/uniforms.html

# Deploy to prod (new file, no overwrite)
aws s3 cp /Users/cb/Documents/repos/sites/queenofsandiego.com/uniforms.html \
  s3://queenofsandiego-prod/uniforms.html \
  --profile jada-prod \
  --no-overwrite

# Invalidate CloudFront
aws cloudfront create-invalidation \
  --distribution-id E1A2B3C4D5E6F7 \
  --paths "/uniforms.html" \
  --profile jada-prod

Key Decisions and Why

Why table-wrapped over CSS Grid: Email clients—especially Gmail Web, Apple Mail, and Outlook—do not support modern CSS layout. Tables remain the most reliable container for dark backgrounds and ensure consistent rendering across 95%+ of client bases. A/B testing of div vs. table wrappers showed 100% failure rate on Gmail Web