49-html-email-template-global

# HTML Email Template (Global)

Email HTML is not web HTML: it needs table layout, inline CSS, and avoidance of everything clients do not support. The bar is simple — it looks right in Gmail, Apple Mail, Outlook, and Yahoo, and it reads on a 375px phone. No exceptions. Content and sequence come from `14-email-marketing-global`; this skill handles the code.

## Information gathering

Read the brand guideline (`46-brand-guideline-global`) and the email content from `14-email-marketing-global` if available. If information is missing, ask up to 4 questions:

1. **Email type and layout?** Welcome, broadcast, nurture, offer, or transactional — single column, two columns with a product image, or a multi-section newsletter?
2. **Which sections?** Header, hero, body, social proof, CTA, footer — is there a hero image?
3. **Is the copy written?** Or should the template ship with placeholders? Where does the primary CTA link?
4. **Which ESP sends it?** Klaviyo, Mailchimp, HubSpot, Brevo, Braze, or other — merge tag syntax differs per platform.

## Principles

1. **Table layout only — no div/flexbox/grid/float/position:absolute.** Outlook on Windows renders through the Word engine and does not support them.
2. **Inline all CSS.** Gmail can strip `<style>` blocks; keep only media queries and dark-mode rules in `<style>`, and inline everything else.
3. **600px maximum width**, degrading to 375px.
4. **System-font fallbacks:** '[body font]', Arial, Helvetica, sans-serif. Never depend on a web font — many clients will not load it.
5. **Every `img` needs alt text plus width and height attributes** so a blocked-image inbox still reads correctly.
6. **Unsubscribe link and a physical postal address are legally required** (CAN-SPAM in the US, GDPR and PECR in the EU/UK, CASL in Canada). Honor opt-outs promptly.
7. **Test on mobile first.** The majority of opens are on a phone.
8. **One self-contained .html file, under 100KB** — Gmail clips messages past roughly 102KB.

## Workflow

### 1. Choose the layout

| Layout | Use for |
|--------|---------|
| Single column | Broadcast, nurture — most readable, fewest rendering bugs |
| Two column (image + text) | Offer emails with a product image |
| Multi-section newsletter | Digest, updates — one table block per section |

### 2. Build to the technical spec

```
Container: 600px desktop / 100% mobile
Outer background: light neutral (e.g. #F4F4F4)
Body background: [background color] (usually white)
Font: '[body font]', Arial, Helvetica, sans-serif
Body font-size: 16px / line-height: 1.6
Mobile breakpoint: max-width 480px
```

Design tokens come from the brand guideline:

- Header: ground [primary color], reversed logo, padding 20px.
- Hero: ground [primary color] or a gradient from [primary color] to [secondary color]; headline bold 28px in a light fill; subtext 16px; CTA button.
- Body: light ground, padding 40x48px desktop / 24x20px mobile; H2 bold 22px in [strong text color]; body 16px, line-height 1.7.
- CTA button: ground [primary color], bold 16px light text, padding 14x32px, radius 8px, `display:inline-block`, no underline. Outlook Windows will not draw `border-radius` — accept the square fallback, and never use an image as the button.
- Social proof: quote on [light background color], 4px left border in [primary color], attributed name and role.
- Footer: light neutral ground, 13px [muted text color] — small logo around 80px, website and social links, postal address, unsubscribe, copyright.

### 3. Fill the sections

- Header: logo, centered.
- Hero: optional preheader text, headline (max 60 characters), subtext (max 100 characters), CTA button, optional hero image 600x300 with alt text.
- Body: greeting with a merge tag, 2-3 opening sentences, main content in short paragraphs (max four sentences), bulleted content built as table rows rather than `ul` for safer rendering, optional secondary CTA.
- Footer (mandatory): company postal address, unsubscribe line ("You are receiving this because you signed up at [website] | Unsubscribe"), copyright.

### 4. Handle mobile and dark mode

```css
@media only screen and (max-width: 480px) {
  /* container: 100% width */
  /* body font: 15px */
  /* CTA: full width, centered */
  /* padding: 24px 20px */
  /* images: 100% width */
}
```

Dark mode:

- Add `<meta name="color-scheme" content="light dark">` and `<meta name="supported-color-schemes" content="light dark">`.
- `@media (prefers-color-scheme: dark)` is only partially supported: Apple Mail honors it well; Gmail typically applies its own color inversion and ignores the media query; Outlook may force a full invert.
- Safe rules when dark mode cannot be controlled: use a transparent-background PNG logo that reads on both light and dark grounds (or add a light stroke); never use pure black text on a transparent ground; give important blocks such as the CTA a solid background color; test in at least one dark-mode client before sending.

### 5. Fill the required placeholders

- First-name merge tag — syntax depends on the ESP
- Unsubscribe link — legally required
- Company postal address — must be real
- Primary CTA link — real URL with UTM parameters per `14-email-marketing-global`

| ESP | First-name merge tag | Unsubscribe |
|-----|----------------------|-------------|
| Klaviyo | `{{ first_name\|default:"there" }}` | `{% unsubscribe %}` |
| Mailchimp | `*\|FNAME\|*` | `*\|UNSUB\|*` |
| HubSpot | `{{ contact.firstname }}` | injected automatically |
| Brevo | `{{ contact.FIRSTNAME }}` | `{{ unsubscribe }}` |

Always confirm the exact syntax in the sending platform before the final send — an unrendered merge tag in a live send is a visible error.

## Email client matrix

| Client | Rendering behavior | What to do about it |
|--------|--------------------|---------------------|
| Gmail (web and app) | May strip `<style>` in some contexts; applies its own dark-mode inversion | Inline everything; the single-column layout must read even if media queries are dropped |
| A