Queen of San Diego — Tech Blog

Under the hood at queenofsandiego.com

Hardening Email Rendering in SES: Why <div> Backgrounds Fail in Gmail and How We Fixed It

A crew-wide uniform requirement email failed to render in Gmail Web, making critical information invisible to 14 team members. The root cause: a seemingly innocent CSS pattern that works in some email clients but gets stripped by Gmail's sandboxing. This post details the rendering bug, the infrastructure fix, and the validation pattern we encoded to prevent recurrence.

The Problem: CSS Stripping in Gmail Web

On May 17, we sent an email announcement using an HTML template with this structure:

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

The intent was a dark navy background with cream text, matching our brand guidelines. In most email clients (Outlook, Apple Mail, Thunderbird), this rendered correctly. In Gmail Web, however, Gmail's security sandbox strips outer <div> style attributes as a cross-origin protection measure. The result: cream-colored text (#f3efe7) rendered on Gmail's white background, becoming invisible.

The fix required understanding Gmail's HTML envelope model: Gmail wraps user-visible content in its own container. Outer wrapper styling is unreliable; only inline styles on <table> and <td> elements survive the sandbox.

Technical Solution: Table-Wrapped Rendering with Defensive Styling

The corrected email template uses explicit table-based layout with redundant styling:

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

Key defensive patterns applied:

  • Table bgcolor attributes: HTML attribute (not CSS) that predates modern email styling; survives in all clients including legacy Outlook versions.
  • Inline style with !important: Overrides Gmail's default email styling cascade.
  • color-scheme: light dark meta tag: Signals to dark-mode-aware clients that the email is designed for dark backgrounds, preventing forced light-theme overrides.
  • Per-cell bgcolor: Every content cell carries its own background color, eliminating reliance on inheritance.

The resend script (/tmp/uniform_resend.py) generated this hardened template and validated it before SES dispatch.

Infrastructure Changes

New Static Page: uniforms.html

Created /Users/cb/Documents/repos/sites/queenofsandiego.com/uniforms.html as a reference page for crew members. The page is:

  • Hosted on S3 bucket: qos-web-prod (CloudFront distribution E1..., Route53 alias queenofsandiego.com)
  • Marked noindex: Not intended for external SEO; internal crew reference only.
  • Styled with dark navy/gold accents: Matches JADA brand guidelines used in email blasts.
  • Two-card layout: Separate sections for ash scattering uniforms vs. standard event uniforms.

Deployment: File pushed to S3 staging, verified via CloudFront cache invalidation, then promoted to production with --no-overwrite flag to preserve existing metadata.

Email Template Memory

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

Rule: Email Outer Wrappers
Outer <div> wrappers with background styling are banned for SES sends. All background color must be applied via <table bgcolor> with !important inline styles on every <td>. Gmail Web strips <div> backgrounds; table-based styling is the only reliable method across major clients.

This rule is now checked before any crew blast is sent.

Blast Tracking and Notification

The corrected email was sent to 14 crew members via AWS SES. The SES MessageId was logged for tracking: 0100019e45b138ad-…

Two parallel notifications were issued:

  • Email resend: 14 crew members received the hardened version with a link to https://queenofsandiego.com/uniforms.html.
  • SMS to Travis Neel (530-262-5427): Sent the new uniform rule + page link via Twilio. Travis explicitly does not receive email blasts, so SMS was the appropriate channel.

Blast logged to the managercandy dashboard (internal progress tracking) at https://progress.queenofsandiego.com/#card-t-1faa1eb1 using the AWS profile configured in ~/.aws/config.

Key Architectural Decisions

Why table-based layout instead of modern CSS Grid? Email clients, particularly Gmail and Outlook Web Access, have sandboxed CSS parsers that pre-date modern CSS. Table-based rendering is the lingua franca of email that works reliably across 99% of clients. While we could generate progressive enhancement versions for modern clients, the risk of invisible text in legacy systems outweighs the styling benefits.

Why bgcolor attributes AND style inline styles? Defense in depth. Some clients (notably Outlook 2007-2010) ignore CSS but respect HTML attributes. Others (Gmail) strip HTML attributes but honor inline styles. By using both, we cover the union of all client behaviors.

Why mark the uniforms page noindex? This page is internal crew documentation, not public-facing. Marking it noindex` prevents search engines from indexing it and cluttering SERP results for "Queen of San Diego uniforms" with an internal logistics page.

Validation Gate Going Forward

Before any SES send, the following checks must pass:

  • No outer <div> wrappers: Grep for <div.*style.*background in the HTML source.
  • All tables have bgcolor: Verify <table> tags carry bgcolor attribute.
  • Every <td> has