---
name: design-email
description: >
  Design and implement transactional and marketing email templates. Use when asked to
  "build an email template", "transactional email", "welcome email", "password reset
  email", "email design", "React Email", "MJML", "dark mode email", or "email copy
  review". Inbox / SPF / spam → enhance-email-deliverability.
license: MIT
---

# design-email — Email Templates That Actually Get Read

**Degree of freedom: MIXED.** Copy and layout judgment `[HIGH freedom]`;
stack detect, markup, send, and preview `[LOW freedom — run exactly]`.

**Email is the one channel users check before they check your app.** A
well-crafted transactional email — clear, warm, fast-loading, and readable on
any device — builds trust. A corporate, jargon-heavy, broken email erodes it.
This skill handles design and copy. Inbox placement / SPF DKIM DMARC is `enhance-email-deliverability`.

## How to reason

1. **Detect** — React Email vs MJML vs none
2. **Audit** — copy voice, subject, one action; client-safe layout
3. **Write** — specific subject, human "you", plain-text twin
4. **Preview** — 375px + dark mode; hand DNS off

## Worked example

> **Detect:** `@react-email/components` already in `package.json`; `emails/` has a receipt only.
> **Audit:** password-reset subject is "Account notification"; two CTAs; no preview text.
> **Write:** subject "Reset your App password"; one "Reset my password" button; expiry in the first sentence.
> **Preview:** `npx email dev` at 375px; tap target ≥44px; DNS/spam → `enhance-email-deliverability`.

## Self-critique before reporting

- **One action** — exactly one primary CTA; subject is specific and honest
- **Client-safe** — 600px single column, inline styles, alt text, dark fallback
- **Human copy** — "you"/"we"; no jargon or ALL-CAPS subject
- **Right owner** — SPF / DKIM / DMARC / bounces / List-Unsubscribe → `enhance-email-deliverability`

---

## Phase 0: Detect the stack  [LOW freedom — run exactly]

```
package.json        → @react-email/*, mjml, nodemailer, @sendgrid/mail,
                      resend, @aws-sdk/client-ses, postmark
emails/             → existing React Email templates
src/emails/         → email template directory
.env.*              → RESEND_API_KEY, SENDGRID_API_KEY, etc. (reference by name only)
```

| Detected framework | Approach |
|--------------------|----------|
| React Email (`@react-email/components`) | JSX components, preview server, multi-client export |
| MJML | XML-like syntax, battle-tested cross-client output |
| None | Implement React Email (current best practice) |

---

## Phase 1: Audit existing templates  [HIGH freedom]

If templates already exist, walk through each one and check:

**Copy quality**:
- Does it sound like a person sent it, or a system?
- Is the subject line specific? ("Your order is on its way" not "Order notification")
- Is the first sentence the most important one (preview text matters)?
- Does it tell the reader exactly what to do and what happens next?
- Is it free of business jargon, technical terms, and passive voice?

**Design**:
- Single-column layout? (Most reliable across clients)
- Max-width 600px? (Standard email width)
- All styles inline? (Gmail strips `<style>` tags)
- Images have `alt` text? (Many clients block images by default)
- Dark mode support? (`@media (prefers-color-scheme: dark)` + inline fallbacks)
- Mobile: tap targets ≥ 44px, font size ≥ 14px

**Sender identity (template-side):**
- "From" address uses the app domain, not a personal Gmail?
- SPF / DKIM / DMARC / bounces → `enhance-email-deliverability`

---

## Phase 2: Research best practices  [HIGH freedom]

```json
firecrawl:firecrawl_search
{
  "query": "transactional email design best practices 2026 React Email",
  "limit": 3,
  "sources": [{ "type": "web" }]
}
```

Fetch React Email docs if using it:
```json
context7:resolve-library-id
{
  "libraryName": "react-email"
}
```

---

## Phase 3: Copy principles  [HIGH freedom]

Apply these to every email before looking at design:

| Principle | How |
|-----------|-----|
| Lead with the most important thing | First line = the key action or news. Not "Hi, we wanted to let you know that…" |
| Subject line = specific, honest | "Your password reset link" not "Important account information" |
| One email, one action | Every email should have exactly one thing it wants the reader to do |
| Write to a person, not an account | "You" not "the user". "We" not "the system". |
| Tell them what happens next | "Click the button below to confirm. The link expires in 24 hours." |
| No jargon | "Your account" not "your profile entity". "Sign in" not "authenticate". |
| Active voice | "We've sent you a link" not "A link has been sent to you" |
| Short paragraphs | 1–2 sentences max. White space is your friend in email. |
| Plain text fallback | Every HTML email should have a plain text version |

### Common email types — copy templates

**Welcome email:**
```
Subject: Welcome to [App Name], [First Name] 👋
Preview: Here's how to get started in 2 minutes.

Hi [First Name],

You're in. [App Name] helps you [core value in 1 sentence].

Here's the first thing to do: [single CTA — most valuable first action].

[Primary Button: Get started]

If you have any questions, just reply to this email.

— [Name], [App Name]
```

**Password reset:**
```
Subject: Reset your [App Name] password
Preview: Your link expires in 1 hour.

Hi [First Name],

Someone requested a password reset for your [App Name] account.
If that was you, click the button below. If not, you can ignore this email.

[Primary Button: Reset my password]

This link expires in 1 hour. After that, you'll need to request a new one.
```

**Billing confirmation:**
```
Subject: Your payment of [amount] was successful
Preview: Next billing date: [date].

Hi [First Name],

Your payment of [amount] for [Plan Name] went through.

Amount: [amount]
Date: [date]
Next billing date: [date]

[Button: View your invoice]

Questions about your bill? Reply here and we'll sort it out.
```

---

## Phase 4: Build the template (React Email)  [LOW freedom — run exactly]

Install if not present:
```bash
npm install react-email @react-email/components
```

Base template structure:
```tsx
// emails/welcome.tsx
import {
  Body, Button, Container, Head, Heading, Hr, Html,
  Link, Preview, Section, Text, Img,
} from '@react-email/components';

interface WelcomeEmailProps {
  firstName: string;
  ctaUrl: string;
}

export function WelcomeEmail({ firstName, ctaUrl }: WelcomeEmailProps) {
  return (
    <Html lang="en">
      <Head />
      <Preview>Welcome to AppName — here's how to get started.</Preview>
      <Body style={body}>
        <Container style={container}>
          <Img src="https://yourdomain.com/logo.png" width="48" height="48" alt="AppName" />
          <Heading style={h1}>Welcome, {firstName}</Heading>
          <Text style={text}>
            You're in. AppName helps you [core value in one sentence].
          </Text>
          <Text style={text}>
            Here's the first thing to do:
          </Text>
          <Section style={btnContainer}>
            <Button style={button} href={ctaUrl}>
              Get started
            </Button>
          </Section>
          <Text style={text}>
            If you have any questions, just reply to this email.
          </Text>
          <Hr style={hr} />
          <Text style={footer}>
            AppName · 123 Street · City · {' '}
            <Link href="{{{UNSUBSCRIBE_URL}}}">Unsubscribe</Link>
          </Text>
        </Container>
      </Body>
    </Html>
  );
}

const body = { backgroundColor: '#f6f9fc', fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif' };
const container = { backgroundColor: '#ffffff', margin: '40px auto', padding: '40px', maxWidth: '600px', borderRadius: '8px' };
const h1 = { fontSize: '24px', fontWeight: '700', color: '#1a1a1a', marginBottom: '16px' };
const text = { fontSize: '16px', lineHeight: '1.6', color: '#444', marginBottom: '16px' };
const btnContainer = { textAlign: 'center' as const, marginBottom: '24px' };
const button = { backgroundColor: '#6366f1', borderRadius: '6px', color: '#fff', fontSize: '16px', fontWeight: '600', padding: '12px 28px', textDecoration: 'none', display: 'inline-block' };
const hr = { borderColor: '#e5e7eb', marginTop: '32px', marginBottom: '32px' };
const footer = { fontSize: '12px', color: '#9ca3af', textAlign: 'center' as const };
```

### Dark mode support

```tsx
// In <Head>:
<style>{`
  @media (prefers-color-scheme: dark) {
    .email-body { background-color: #1a1a1a !important; }
    .email-container { background-color: #2d2d2d !important; }
    .email-text { color: #e5e7eb !important; }
    .email-heading { color: #f9fafb !important; }
  }
`}</style>
// Add className to Body, Container, Text, Heading components to match
```

---

## Phase 5: Send via provider  [LOW freedom — run exactly]

### Resend (recommended for new projects)

```typescript
import { Resend } from 'resend';
import { WelcomeEmail } from '../emails/welcome';
import { render } from '@react-email/render';

const resend = new Resend(process.env.RESEND_API_KEY);

await resend.emails.send({
  from: 'AppName <hello@yourdomain.com>',
  to: user.email,
  subject: `Welcome to AppName, ${user.firstName}`,
  react: <WelcomeEmail firstName={user.firstName} ctaUrl={ctaUrl} />,
});
```

### Add a Supabase Edge Function trigger (if using Supabase)

```typescript
// supabase/functions/send-welcome-email/index.ts
import { serve } from 'https://deno.land/std/http/server.ts';
import { Resend } from 'npm:resend';

serve(async (req) => {
  const { record } = await req.json(); // from a database webhook
  const resend = new Resend(Deno.env.get('RESEND_API_KEY'));
  await resend.emails.send({
    from: 'AppName <hello@yourdomain.com>',
    to: record.email,
    subject: `Welcome to AppName!`,
    html: '...', // rendered HTML
  });
  return new Response('OK');
});
```

Deploy:
```bash
supabase functions deploy send-welcome-email --no-verify-jwt
```

---

## Phase 6: Content flags that hurt placement  [LOW freedom — do not skip]

DNS auth, bounces, and List-Unsubscribe headers are `enhance-email-deliverability`.
This phase only owns copy/markup that templates can fix:

- [ ] From address uses your domain (not `noreply@gmail.com`)
- [ ] Reply-To set if replies should go somewhere useful
- [ ] No ALL-CAPS words in subject line
- [ ] No spam trigger words: "FREE", "URGENT", "ACT NOW", "GUARANTEED"
- [ ] Plain text version matches the HTML version
- [ ] Hand remaining inbox-placement work to `enhance-email-deliverability`

---

## Phase 7: Preview and test  [LOW freedom — run exactly]

Start the React Email preview server:
```bash
npx email dev --dir emails --port 3001
```

Then check with Playwright:
```bash
PW="npx --yes @playwright/cli@latest"
$PW -s=email-preview open --headed http://localhost:3001
$PW -s=email-preview snapshot                                  # verify each template renders
$PW -s=email-preview resize 375 812                            # mobile — font size, tap targets
$PW -s=email-preview screenshot --filename ".playwright-mcp/email-mobile.png"
```

For cross-client testing, use Litmus or Email on Acid. Key clients to test:
- Gmail (web + Android + iOS)
- Apple Mail (macOS + iOS)
- Outlook (Windows — most restrictive CSS support)
- Samsung Mail

---

## Email templates checklist

```
Design:
- [ ] Max-width 600px
- [ ] Single column
- [ ] All styles inline (no <style> blocks except dark mode)
- [ ] Images have alt text
- [ ] Buttons ≥ 44px tall, large enough to tap
- [ ] Font size ≥ 14px on body text
- [ ] Dark mode tested

Copy:
- [ ] Subject line is specific and honest
- [ ] Preview text set and meaningful
- [ ] First sentence is the most important thing
- [ ] Exactly one primary action
- [ ] Copy sounds like a person wrote it
- [ ] No jargon or passive voice
- [ ] Plain text version exists

Deliverability (handoff — do not own here):
- [ ] From address on app domain
- [ ] Plain-text alternative present
- [ ] SPF / DKIM / DMARC / bounces / unsubscribe headers → `enhance-email-deliverability`
```