Email Template Design skill for Codex

A finished email reads correctly with images off, in dark mode, at 320px wide and in classic Outlook for Windows; the important message and action are visible above the fold; the HTML stays under Gmail’s clipping limit; and a plain-text part says the same thing. Email HTML is its own platform: web CSS habits break here.

Source format

Situation	Use
New templates, no existing system	MJML: compiles to table-based HTML with Outlook conditionals included
React codebase already sending with React Email	Keep React Email components; same design rules apply
Team uses Tailwind and wants a build pipeline	Maizzle
One-off fix to an existing hand-coded template	Edit the HTML; read references/client-quirks.md first

Read AGENTS.md and look for existing templates and the sending path before choosing (rg -l "mjml|@react-email|maizzle|sendgrid|postmark|resend|nodemailer|ses" --glob '!**/node_modules/**'). Templates often contain placeholders for an ESP or a templating engine (Handlebars, Liquid); keep their syntax intact.

Workflow

• Content first: subject, preheader, one primary message, one primary CTA.
• Layout: single column, 600px, sections stacked; two columns only for small grids.
• Build in MJML with shared mj-attributes; compile and validate.
• Add dark mode, plain text, alt text, lang, and preheader.
• Preview locally (browser + Mailpit), check size, then test in real clients.
• Send to any real inbox or list only after the user confirms recipients.

Design rules

• Width 600px; body text 16px with 24px line height; headings 22-28px.
• System or safe font stacks; web fonts only as enhancement (Inter, Arial, Helvetica, sans-serif). Outlook and Gmail ignore most web fonts.
• One primary CTA as a button at least 44px tall, repeated at the bottom for long emails.
• Key message in live text, not inside images. Image-only emails show nothing when images are blocked and are flagged by spam filters.
• Contrast at least 4.5:1; links underlined in body copy.
• Mobile: columns stack below 480px (MJML default), tap targets at least 44px, padding 16-24px.

MJML skeleton

<mjml lang="en">
  <mj-head>
    <mj-title>Your invoice from Acme</mj-title>
    <mj-preview>Invoice 1042 for $49.00 is ready - due 12 Nov</mj-preview>
    <mj-attributes>
      <mj-all font-family="Inter, Arial, Helvetica, sans-serif" />
      <mj-text font-size="16px" line-height="24px" color="#1f2937" padding="0 0 16px" />
      <mj-button background-color="#1f4fd8" color="#ffffff" font-size="16px" font-weight="600"
                 border-radius="6px" inner-padding="14px 24px" />
      <mj-section padding="0" />
    </mj-attributes>
    <mj-style>
      @media (prefers-color-scheme: dark) {
        .card { background: #111827 !important; }
        .card div { color: #e5e7eb !important; }
      }
    </mj-style>
    <mj-raw>
      <meta name="color-scheme" content="light dark">
      <meta name="supported-color-schemes" content="light dark">
    </mj-raw>
  </mj-head>
  <mj-body width="600px" background-color="#f3f4f6">
    <mj-section padding="24px 0">
      <mj-column>
        <mj-image src="https://cdn.example.com/email/[email protected]" width="120px" alt="Acme" align="left" padding="0 24px" />
      </mj-column>
    </mj-section>
    <mj-section css-class="card" background-color="#ffffff" padding="32px 24px" border-radius="8px">
      <mj-column>
        <mj-text font-size="24px" line-height="32px" font-weight="700">Invoice 1042 is ready</mj-text>
        <mj-text>Hi {{first_name}}, your invoice for <strong>$49.00</strong> is due on 12 November.</mj-text>
        <mj-button href="https://app.example.com/invoices/1042">View invoice</mj-button>
        <mj-text font-size="14px" color="#4b5563">Questions? Reply to this email.</mj-text>
      </mj-column>
    </mj-section>
    <mj-section padding="24px">
      <mj-column>
        <mj-text font-size="12px" line-height="18px" color="#6b7280" align="center">
          Acme Inc, 1 Harbor St, Springfield. <a href="{{unsubscribe_url}}" style="color:#6b7280">Unsubscribe</a>
        </mj-text>
      </mj-column>
    </mj-section>
  </mj-body>
</mjml>

npx mjml src/invoice.mjml -o dist/invoice.html --config.validationLevel=strict   # network on first npx run
npx mjml -w src/invoice.mjml -o dist/invoice.html                                # watch while editing

Add mjml as a dev dependency with the project’s package manager rather than relying on npx in CI.

Dark mode

Clients behave in three ways: no change (some webmail), full or partial color inversion (Gmail app, Outlook), or honouring prefers-color-scheme (Apple Mail, some Outlook).

• Declare color-scheme meta tags (as above) and provide dark styles in a media query.
• Logos: use transparent PNGs with a light stroke or a version that works on both; or place the logo on a fixed light “pill” background.
• Avoid pure #ffffff/#000000 pairs; inversion engines treat near-white and near-black more gently.
• Outlook.com dark mode adds data-ogsc attributes; target them only when a specific element breaks.

Images

• Host on HTTPS with absolute URLs. Export at 2x and set the display width attribute.
• Every <img> gets alt; decorative images get alt="".
• Keep total image weight under about 1 MB; GIFs: first frame must carry the message.
• Background images need VML for Outlook; MJML’s background-url on mj-section generates it. Always set a fallback background-color.

Plain text and headers

Generate a plain-text part with the same content and the full URLs. Most ESPs auto-generate one; review it, because generated text often includes layout junk. Transactional sending services also expect a List-Unsubscribe header for bulk mail, and marketing mail legally needs an unsubscribe link and a postal address in many jurisdictions; flag this for the user rather than assuming compliance.

Size and clipping

Gmail clips messages over about 102 KB of HTML. Check:

wc -c dist/invoice.html     # aim for under 80 KB to leave room for ESP tracking rewrites

Reduce by removing comments, using mj-attributes instead of repeated inline attributes, and minifying (--config.minify=true in MJML 4, or a separate HTML minifier).

Testing

1. Open dist/*.html in a browser at 600px and 320px; toggle dark mode in devtools.
2. Disable images (block the image host in devtools) and confirm the message survives.
3. Send through a local SMTP catcher such as Mailpit (mailpit binary or Docker image; UI on port 8025, SMTP on 1025) so nothing leaves the machine. Point the app’s dev SMTP settings at it.
4. Real-client rendering: Litmus or Email on Acid (paid, needs network) or test accounts in Gmail, Outlook.com and classic Outlook for Windows.

Sending to real addresses, seed lists or customers is outward-facing: show the user the recipient list and get explicit confirmation before any send.

Gotchas

• Flexbox, grid, position, CSS variables, max-width (Outlook), and margin on block elements (Outlook) do not work reliably. Tables and padding on cells do.
• Gmail drops the entire <style> block if it hits a syntax error; keep critical styles inline (MJML inlines mj-attributes output).
• Preheader text: if the content is shorter than the preview pane, clients pull in the next text (“View in browser”). MJML’s mj-preview pads it; keep it 40-110 characters.
• Template variables inside attributes (href="{{url}}") must survive compilation; check the compiled HTML, especially with mj-raw and minification.
• Links to localhost or staging hosts in production templates. Grep compiled output before shipping: rg -n "localhost|staging|example\.com" dist/.

Verification checklist

• mjml --config.validationLevel=strict compiles with no errors.
• HTML size under 80 KB; images absolute HTTPS with alt text.
• Renders at 320px and 600px; dark mode readable; images-off readable.
• Classic Outlook check done (real client or rendering service) or listed as untested.
• Plain-text part reviewed; unsubscribe and address present for marketing mail.
• No test or localhost links in compiled output.

For per-client fixes (Outlook VML, DPI scaling, Gmail style stripping), read references/client-quirks.md when a specific client misrenders. Lifecycle strategy and deliverability belong to $email-marketing.