Claude Skill

Email HTML Builder

Generates transactional or marketing email HTML that survives Outlook, Gmail dark mode, and mobile clients.

Download skill (.zip)Or download whole pack

What it does

Produces table-based, inline-CSS email HTML that renders consistently across Gmail, Outlook (including the legacy desktop renderer), Apple Mail, and mobile clients. Handles dark mode, bulletproof buttons, retina images, and a plain-text fallback. Use for transactional (receipts, password reset) or simple marketing (announcement, digest).

When to use

✓You're sending email from your own backend (Postmark, SES, Resend, SendGrid)
✓Existing email template renders broken in Outlook or dark mode
✓You need a reliable transactional template (receipt, magic link, welcome)

When not to use

✗You're using a drag-and-drop builder (Mailchimp, Customer.io UI, Klaviyo) — let it generate
✗Highly designed campaign with custom layout — work with a designer who knows email
✗AMP for Email — different format, different rules

Install

Download the .zip, then unzip into your Claude skills folder.

mkdir -p ~/.claude/skills
unzip ~/Downloads/email-html-builder.zip -d ~/.claude/skills/

# Restart Claude Code session.
# Skill is now available — Claude will use it when relevant.

SKILL.md

---
name: email-html-builder
description: Use when generating HTML email that must render across Gmail, Outlook, Apple Mail, and mobile clients. Triggers on "build email HTML", "transactional email template", "email template", "newsletter HTML".
---

# Email HTML Builder

Email rendering is hostile. Outlook 2007-2019 still uses Word's HTML engine. Gmail strips `<style>` from `<head>` for clipped messages. Dark mode in Apple Mail inverts colors unpredictably. Generate HTML that survives all of it.

## Required inputs

1. **Email type** — transactional (single purpose, single CTA) vs marketing (multiple stories)
2. **Sender brand** — logo URL (hosted, not base64), brand color hex, accent color
3. **Subject line** + **preheader text** (the gray text after the subject in inbox)
4. **Single primary CTA** — text + URL. Transactional emails get ONE CTA.
5. **Body content** — copy, image URLs (must be hosted, public, with explicit width/height)
6. **Footer requirements** — physical address (CAN-SPAM), unsubscribe link (marketing), company name

## Output format

**Table-based layout, inline CSS, max width 600px.** This is non-negotiable for Outlook compatibility. Tailwind is fine for prototyping the look, but the final output must inline styles.

Use a tool like `mjml` or `maizzle` if available — they compile to bulletproof HTML. Otherwise, hand-write tables.

Wrapper structure:

```
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width">
    <meta name="x-apple-disable-message-reformatting">
    <meta name="color-scheme" content="light dark">
    <meta name="supported-color-schemes" content="light dark">
    <title>...</title>
    <!-- All other styles inline. <style> tags are unreliable. -->
  </head>
  <body style="margin:0; padding:0; background:#f4f4f5;">
    <!-- Preheader: hidden but pulled into inbox preview -->
    <div style="display:none; max-height:0; overflow:hidden;">{{preheader}}</div>
    <table role="presentation" width="100%" cellpadding="0" cellspacing="0" border="0">
      <tr><td align="center">
        <table role="presentation" width="600" ...>
          <!-- content -->
        </table>
      </td></tr>
    </table>
  </body>
</html>
```

## Layout structure

1. **Preheader** — 50-90 chars, hidden div. Repeats subject value-prop.
2. **Header** — logo (no taller than 40px), centered or left-aligned
3. **Hero** (marketing only) — single image, max 600px wide, retina @2x exported at half-size
4. **Body** — `<td style="padding:32px;">`, font-family stack `-apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif`, line-height 1.5
5. **CTA button** — bulletproof button (VML for Outlook + table fallback). NEVER a styled `<a>` alone.
6. **Footer** — small print, sender address, unsubscribe link

## Bulletproof button (VML for Outlook)

```
<!--[if mso]>
<v:roundrect xmlns:v="urn:schemas-microsoft-com:vml" href="{{url}}" style="height:48px;v-text-anchor:middle;width:240px;" arcsize="12%" stroke="f" fillcolor="#4f46e5">
  <w:anchorlock/>
  <center style="color:#ffffff;font-family:Arial,sans-serif;font-size:16px;font-weight:bold;">{{text}}</center>
</v:roundrect>
<![endif]-->
<!--[if !mso]><!-->
<a href="{{url}}" style="background:#4f46e5;border-radius:6px;color:#ffffff;display:inline-block;font-family:-apple-system,Helvetica,Arial,sans-serif;font-size:16px;font-weight:600;line-height:48px;text-align:center;text-decoration:none;width:240px;">{{text}}</a>
<!--<![endif]-->
```

## Dark mode handling

Apple Mail and Outlook (Mac/iOS) auto-invert colors. Two strategies:

1. **Light-only mode**: add `<meta name="color-scheme" content="light">`. Brand stays consistent but ignores user preference.
2. **Adaptive**: design two color sets, use `@media (prefers-color-scheme: dark)` (works in Apple Mail), provide light/dark logo variants. Test in Litmus or Email on Acid.

For logos: use PNGs with a 1px transparent border around dark text — prevents Outlook auto-color-inversion making logos invisible.

## Plain-text fallback

ALWAYS provide `text` alongside `html` in your sending API. Plain text version:
- Same content, no markup
- URLs spelled out (not `[click here]`)
- Same unsubscribe link

Most ESPs auto-generate a poor plain-text version — write it explicitly.

## Anti-patterns

- **Web fonts via `@import`**: stripped by Gmail. Use system fonts or fall back gracefully.
- **Background images**: unsupported in Outlook. Use solid colors or VML fallback.
- **CSS `flex` / `grid`**: don't work in Outlook. Use tables.
- **`position: absolute`**: ignored or breaks layout. Use table cells.
- **SVG**: poorly supported. Use PNG.
- **Missing `alt` text on images**: Outlook blocks images by default. Without `alt`, your email is blank squares.
- **Linking the entire email block to one URL**: clicks get attributed weirdly. Link explicit elements.

## Testing

Recommend the user test in:
- Gmail web (light + dark)
- Apple Mail (iOS + macOS, light + dark)
- Outlook 2019 desktop (the strict renderer)
- Outlook.com web
- Litmus or Email on Acid for full coverage

If you can't test, default to the most conservative HTML.

## Output

Return the full HTML file + a plain-text version. Add a top comment listing:
- Tested-against client list (or "untested — recommend Litmus before send")
- Inline CSS (yes/no)
- Dark mode strategy
- Image hosting reminder (no base64)

Example prompts

Once installed, try these prompts in Claude:

Build a password reset email HTML. Single CTA "Reset password", expires in 1 hour, fallback link, dark mode safe.
Generate a monthly digest email — header, 3 article cards with image+title+excerpt, footer with unsubscribe.