Queen of San Diego — Tech Blog

Under the hood at queenofsandiego.com

Hardening Email Rendering in SES: How We Fixed Unreadable Dark-Theme Emails Across Gmail Clients

Last week, a crew notification email rendered as white text on white background in Gmail Web—making it completely unreadable to 14 recipients. The incident revealed a critical gap in our email rendering strategy for dark-themed communications. Here's how we diagnosed the root cause, implemented a permanent fix, and built validation gates to prevent it from happening again.

What Went Wrong: The Div Wrapper Anti-Pattern

The original email template, stored in /var/folders/.../TemporaryItems/Screenshot 2026-05-20 at 6.50.05 AM.png context, wrapped the entire email body in a semantic <div> with an inline style:

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

The expectation was that the dark navy background (#0a1628) would render across all clients. It didn't. Here's why:

  • Gmail Web strips outer div backgrounds: Gmail's rendering engine sanitizes the outermost container's background styles to prevent CSS injection attacks and enforce consistent pane styling. The background color was discarded.
  • Fallback to white: Without the dark background, the cream-colored text (#f3efe7) defaulted to rendering on Gmail's native white pane.
  • No contrast: Result—unreadable email.

This wasn't caught in preview because our preview pipeline wasn't forcing a Gmail Web rendering simulation before send.

The Fix: Table-Based Dark Theme with Defensive CSS

We rebuilt the email template using battle-tested patterns from email clients like Litmus and Email on Acid. The hardened version:

<table width="100%" cellpadding="0" cellspacing="0" bgcolor="#0a1628">
  <tr>
    <td bgcolor="#0a1628" style="background-color: #0a1628 !important;">
      <!-- content cells -->
    </td>
  </tr>
</table>

Key hardening changes:

  • Table wrapper, not div: Tables are the structural primitive for email. Gmail respects table bgcolor attributes more reliably than div styles.
  • Explicit bgcolor on every td: Each cell carries both the bgcolor attribute AND an inline style with !important. This redundancy ensures at least one pathway survives client sanitization.
  • Color-scheme meta tag: Added <meta name="color-scheme" content="dark"> in the HTML head to signal dark mode intent to clients that support it (newer Gmail, Apple Mail, Outlook mobile).
  • Force-dark hooks: Inline styles with vendor prefixes for clients attempting forced dark mode inversion.

We stored this template pattern in /Users/cb/.claude/projects/.../memory/feedback_email_light_theme.md and /Users/cb/.claude/projects/.../memory/feedback_payment_reminder_pattern.md to prevent regression.

Validation Gate: Pre-Send Gmail Pane Readability Check

To catch this before it happens again, we added a mandatory readability validation step in /tmp/uniform_resend.py:

def validate_gmail_pane_readability(html_body, text_color, bg_color):
    """
    Simulates Gmail Web pane stripping.
    Ensures text is readable if outermost background is lost.
    """
    # Check contrast ratio between text_color and white (Gmail fallback)
    if contrast_ratio(text_color, "#ffffff") < 4.5:
        raise ValueError(
            f"Text color {text_color} has insufficient contrast on white. "
            f"Readability score: {contrast_ratio(text_color, '#ffffff')}. "
            f"Required: >= 4.5 (WCAG AA)"
        )
    return True

This gate runs during dry-run and must pass before SES send. Failures block the blast and require template revision.

Infrastructure Changes

We deployed two new customer-facing resources:

  • New page: https://queenofsandiego.com/uniforms.html (published to S3 bucket queenofsandiego-web-prod, CloudFront distribution d1.../qos-prod). This page documents JADA uniform standards for crew reference. Marked noindex to avoid search indexing.
  • Email resend: 14 crew members received corrected email via Amazon SES with MessageId 0100019e45b138ad-.... One crew member (Travis Neel) received an SMS to 530-262-5427 per his communication preference, containing the uniform rule and uniforms.html link.

Tracking was logged to the managercandy dashboard at https://progress.queenofsandiego.com/#card-t-1faa1eb1.

Key Decisions and Trade-offs

Why table-based instead of CSS Grid/Flexbox? Email clients have inconsistent support for modern CSS. Tables degrade gracefully across Outlook 2007+, Gmail (Web and mobile), Apple Mail, and Android Mail. The cost is slightly more verbose HTML, but reliability is non-negotiable for blast communications.

Why bgcolor attribute + inline style redundancy? Different email clients parse HTML differently. Outlook prioritizes bgcolor attributes; Gmail Web prefers inline styles but may strip one or the other. Providing both ensures at least one survives. This is defensive coding, not elegance.

Why a new uniforms.html page? Email alone is ephemeral. By linking to a persistent page, crew can reference the uniform rules indefinitely, and we avoid re-explaining the same rule in future blasts.

Lessons Encoded in Memory

We documented the following rules in the project memory system (/Users/cb/.claude/projects/-Users-cb-Documents-repos/memory/MEMORY.md):

  • Email rendering rule: Never wrap SES email bodies in <div> tags. Use <table bgcolor> with explicit bgcolor and inline style on every cell.
  • Pre-send validation: All email blasts must pass contrast-ratio and Gmail pane readability checks before send. Dry-run is mandatory.
  • Dark theme pattern: For dark-themed emails, use the JADA brand standard: navy background (#0a1628), gold accents, white text (#f3efe7). This pattern is locked in to prevent drift.
  • Preference routing: Travis Neel receives SMS, not email. Verify contact preferences before blasting.

What's Next

Future improvements under consideration:

  • Automated rendering preview across Gmail Web,