---

name: design-email description: > Design and build transactional and marketing email templates. Use when "build an email template", "welcome email", "password reset email", "React Email", "MJML", "dark mode email", or "email copy review". Spam/SPF → 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]

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

Fetch React Email docs if using it:

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

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.

Welcome (subject with first name, preview "get started in 2 minutes", one Get started button, "just reply" close) and Billing confirmation (subject "Your payment of [amount] was successful", amount/date/next billing date lines, View your invoice button): references/copy-templates.md.

---

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

Install if not present:

npm install react-email @react-email/components

Base template structure: Html lang → Head → Preview → Body → Container (600px max, white on off-white) with Img logo (alt text), Heading, Text, one Button in a centered Section, Hr, and a footer Text with address + {{{UNSUBSCRIBE_URL}}} link. Styles are inline objects; swap the indigo button and off-white ground for the brand. Full emails/welcome.tsx: references/react-email-and-send.md §Base template.

Dark mode support

// 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)

new Resend(process.env.RESEND_API_KEY) → resend.emails.send({ from: 'AppName <hello@yourdomain.com>', to, subject, react: <WelcomeEmail … /> }). Code: references/react-email-and-send.md §Send with Resend.

Add a Supabase Edge Function trigger (if using Supabase)

supabase/functions/send-welcome-email/index.ts: Deno serve, read record from the database webhook body, npm:resend with Deno.env.get('RESEND_API_KEY'), send rendered HTML, return OK. Code: references/react-email-and-send.md §Supabase Edge Function trigger.

Deploy:

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:

npx email dev --dir emails --port 3001

Then check with Playwright:

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`