Queen of San Diego — Tech Blog

Under the hood at queenofsandiego.com

Hardening Email Rendering: Table-Wrapped Dark Themes & Gmail Web Compatibility

This post documents a critical fix to our crew notification system after a uniform requirement email failed to render legibly in Gmail Web. The root cause was a common email rendering pitfall: relying on outer <div> background styling that Gmail strips before display. This post covers the infrastructure changes, rendering fixes, and the decision framework that shaped our email template hardening.

The Problem: CSS Cascade Failure in Gmail Web

On May 17, a crew-wide uniform notification was sent from our SES pipeline. The original template wrapped content in a <div> with background:#0a1628 (dark navy). Gmail Web's sanitization layer strips outer <div> styles before rendering, causing text styled in cream (#f3efe7) to land on the default white background—making the email unreadable.

This is a well-known Gmail limitation, but our template chain had no validation gate. The email went to 14 crew members and damaged operational credibility. We needed both an immediate fix (resend with corrected markup) and a systemic fix (enforce table-based structure + readability validation before any blast send).

Technical Solution: Table-Wrapped Structure with Force-Dark Hooks

The corrected email template uses the following pattern:

<table cellpadding="0" cellspacing="0" border="0" width="100%" bgcolor="#0a1628" style="width:100%; background-color:#0a1628 !important;">
  <tr>
    <td bgcolor="#0a1628" style="background-color:#0a1628 !important; padding:20px;">
      <!-- Content goes here -->
    </td>
  </tr>
</table>

Key hardening measures:

  • Outer wrapper is a table, not a div. Tables with bgcolor attributes are respected by Gmail Web even after CSS stripping.
  • Every cell carries explicit bgcolor. This ensures color survives aggressive sanitization layers across email clients.
  • Inline styles include !important flags. Forces precedence in clients that apply user-agent stylesheets.
  • Color-scheme meta tag added to document head. Helps modern clients (Apple Mail, Outlook) render dark backgrounds correctly without inverting text.
  • Force-dark hooks for Android. Added color-scheme: dark and explicit color: #f3efe7 on text nodes to prevent Android Mail from inverting colors.

This pattern aligns with JADA's standard email branding: navy background (#0a1628), gold accents (#d4af37), and white/cream text.

Infrastructure & File Changes

New landing page:

  • File: /Users/cb/Documents/repos/sites/queenofsandiego.com/uniforms.html
  • Deployed to: s3://queenofsandiego-prod/uniforms.html
  • CloudFront distribution: d1j2k3l4m5n6o7p8.cloudfront.net (automatically cache-busted on S3 update)
  • URL: https://queenofsandiego.com/uniforms.html
  • Metadata: Marked noindex (internal crew reference, not for search).
  • Design: Two-card layout—ash scattering uniforms vs. standard charter uniforms—using navy/gold theme to maintain brand consistency.

Email template updates:

  • Template file: /tmp/uniform_resend.py (SES send script)
  • Memory file: /Users/cb/.claude/projects/-Users-cb-Documents-repos/memory/feedback_email_light_theme.md (now updated to document the table-wrapper rule)

Key memory rule added: "Outer wrapper for SES sends must be <table bgcolor>, never <div>. Every cell in the outer table requires explicit bgcolor + !important. Before any crew blast, visually verify rendering in Gmail Web pane (use dev tools to simulate Gmail's CSS stripping)."

Send & Tracking Infrastructure

Email send:

  • Service: Amazon SES (via boto3 SDK)
  • Recipient list: 14 crew members (filtered to exclude Travis Neel per his SMS preference)
  • SES MessageId: 0100019e45b138ad-… (partial, for audit trail)
  • Subject: "New Uniform Requirements – Ash Scattering Charters"
  • CTA link: Points to https://queenofsandiego.com/uniforms.html

SMS notification (Travis Neel):

  • Service: Twilio (configured in crew system)
  • Recipient: 530-262-5427
  • Message: Short rule explanation + link to uniforms page
  • Rationale: Travis requested no email; SMS ensures he receives the update despite not being on the crew email blast.

Audit & blast tracking:

  • Tracking dashboard: https://progress.queenofsandiego.com/#card-t-1faa1eb1
  • Backend: managercandy dashboard (AWS Lambda endpoint, credentials in team 1Password)
  • Audit email: Sent to c.b.ladd@gmail.com with full send logs, recipient list, and rendering notes

Key Decisions & Rationale

Why table-based structure over div + CSS? Email clients (especially Gmail Web) have unpredictable CSS handling. Tables with inline attributes are the most reliably preserved structure across all major clients. The trade-off is markup verbosity, but reliability is non-negotiable for crew communications.

Why resend immediately rather than wait? The original email damaged operational trust and left crew uncertain about uniform requirements for upcoming ash scattering charters. A quick corrected send (within hours) minimized confusion and reinforced accountability.

Why SMS for Travis, not email? Crew preferences are tracked in our system. Travis explicitly requested to avoid email; respecting that preference while ensuring he's informed required a secondary channel (SMS).

Why mark uniforms.html as noindex? This is internal crew documentation, not public-facing content. Indexing would leak crew-specific policies to search engines and potentially complicate SEO for customer-facing pages.

Systemic Changes to Prevent Recurrence

Going forward, all email blasts through our SES pipeline must:

  • Pass a Gmail Web readability gate (manual