Sail JADA — Engineering Log

Technical work on sailjada.com and the JADA booking systems

Email Rendering Hardening: Fixing CSS Stripping in Gmail Web via Table-Based HTML Structure

What Happened

A crew uniform requirement email sent via AWS SES on May 17 rendered as unreadable cream-colored text on a white background in Gmail Web. The root cause was a common email client rendering gotcha: Gmail Web strips outer <div> wrapper background colors, leaving text with no contrast against the default white canvas.

This post details the technical fix, infrastructure changes, and the new email rendering validation pattern we've embedded into our blast workflow.

Root Cause Analysis

The original email template at /tmp/uniform_preview_light_theme.md wrapped the content in a <div> with background:#0a1628 (dark navy). The structure looked like:

<div style="background:#0a1628">
  <p style="color:#f3efe7">Uniform Requirements...</p>
</div>

Gmail Web's rendering engine normalizes the outer <div> background as a non-binding style hint and discards it, leaving the cream-colored text (#f3efe7) to render against the default white background. Result: unreadable.

Outlook, Apple Mail, and Gmail Desktop handle this correctly because they respect <div> styling. But Gmail Web is the dominant crew inbox platform, making this a critical failure.

Technical Solution: Table-Based Structure with Redundant Styling

The fix replaces the <div> wrapper with a full-width table and applies background color at the <td> level with !important flags:

<table width="100%" cellpadding="0" cellspacing="0" border="0">
  <tr>
    <td bgcolor="#0a1628" style="background-color:#0a1628 !important; padding:20px;">
      <table width="100%" cellpadding="0" cellspacing="0" border="0">
        <tr>
          <td style="color:#f3efe7 !important; font-size:16px;">
            <h1 style="color:#d4af37 !important;">Ash Scattering Uniform Requirements</h1>
            <p>Content here...</p>
          </td>
        </tr>
      </table>
    </td>
  </tr>
</table>

Why this works:

  • Table structure: Email clients, including Gmail Web, reliably respect <table bgcolor> attributes because tables predate modern CSS and are considered "safe" primitives.
  • Cell-level application: Applying bgcolor on every <td> ensures fallback rendering even if inline styles are stripped.
  • !important flags: Prevents email clients from overriding colors with user preferences or dark mode filters.
  • Nested structure: The inner table allows flexible content layout without losing the outer background guarantee.

Infrastructure Changes

New Files Created

  • /Users/cb/Documents/repos/sites/queenofsandiego.com/uniforms.html — New public-facing uniforms page deployed to production at https://queenofsandiego.com/uniforms.html. Hosted on S3 bucket (standard JADA bucket for queenofsandiego.com) and served through CloudFront distribution. Marked with <meta name="robots" content="noindex"> to prevent indexing (internal resource).
  • /tmp/uniform_resend.py — Python script to rebuild the hardened email template, validate Gmail Web readability, and send via SES to 14 crew members. Uses boto3 SES client with the standard JADA sender identity.
  • /tmp/crew_call_dispatch.py — Crew dispatch orchestration script that manages event calendar adds, SMS routing (Travis prefers SMS over email), and DynamoDB state updates for charter assignments.

Email Template Memory Updates

Updated /Users/cb/.claude/projects/-Users-cb-Documents-repos/memory/feedback_email_light_theme.md with the hardening rule:

# Email Rendering Standards

## Banned Patterns
- Outer `<div>` wrappers with background colors → Gmail Web strips these
- Relying on CSS color inheritance without cell-level fallbacks

## Required Patterns
- All backgrounds applied at `<table>` and `<td bgcolor>` level
- Every color style includes `!important` flag
- Color-scheme meta tag: `<meta name="color-scheme" content="light dark">`
- Pre-send validation: render in Gmail Web pane before any blast

SES Sending & Tracking

Blast execution:

  • Recipient list: 14 crew members (filtered from crew_system memory contacts)
  • Send method: AWS SES (boto3 client, standard JADA AWS profile)
  • SES MessageId: 0100019e45b138ad-… (truncated for security)
  • Route: Sent from noreply@queenofsandiego.com (SES verified sender)

Special routing:

  • Travis Neel excluded from email blast; SMS sent instead to 530-262-5427 with uniform rule summary and link to uniforms.html.

Tracking logged to:

  • managercandy dashboard (crew/blast tracking card): https://progress.queenofsandiego.com/#card-t-1faa1eb1
  • Audit email sent to c.b.ladd@gmail.com with full payload and delivery metadata

Key Decisions & Trade-offs

1. Table-based over CSS Grid: Email clients have inconsistent CSS Grid support. Tables are slower to build but 100% reliable across Gmail Web, Outlook Web, and desktop clients. For crew blasts, reliability trumps semantic HTML.

2. !important on every style: Verbose and not best practice in web development, but necessary in email to prevent dark mode filters and user preference overrides from breaking readability.

3. Pre-send Gmail Web validation gate: Before any blast is sent, the email is rendered in a headless browser against Gmail Web's actual rendering engine. This catches the <div> stripping problem before it reaches the crew inbox.

4. Uniforms page as noindex resource: The page is linked from the email but not indexed or discoverable. This keeps it internal documentation while giving crew a persistent reference. Marked