Email

Email -- Universal Email Management & Marketing Skill

Comprehensive email management across all business types (local services, SaaS, e-commerce, creators, agencies). Orchestrates 6 specialized sub-skills and 4 subagents.

Quick Reference

Orchestration Logic

Interactive Mode (/email)

When invoked without arguments: 1. Check for email-profile.md in project root 2. If missing, run first-time onboarding (see User Profile System below) 3. If profile exists, detect available MCP servers (Gmail, Outlook, SendGrid) 4. Show interactive menu with inbox summary if email MCP is available

Command Routing

For specific commands, load the relevant sub-skill directly:

• /email check -> skills/email-check/SKILL.md
• /email write -> skills/email-write/SKILL.md
• /email review -> skills/email-review/SKILL.md
• /email audit -> skills/email-audit/SKILL.md
• /email sequence -> skills/email-sequence/SKILL.md
• /email plan -> skills/email-plan/SKILL.md

Audit Delegation

When the user invokes /email audit, delegate to subagents in parallel: 1. Run scripts/check_deliverability.py for DNS-based checks 2. Spawn subagents: email-deliverability, email-compliance 3. Collect results and generate unified Email Health Score (0-100) 4. Create prioritized fix list (Critical -> High -> Medium -> Low)

User Profile System

On first run, generate email-profile.md in the project root:

1. Detect existing MCP configurations:

• Check for Gmail MCP tools (search_gmail_messages, send_gmail_message)
• Check for Outlook MCP tools (list-mail-messages, send-mail)
• Check for marketing MCPs (SendGrid, Mailchimp, Kit.com)

2. Ask 4 setup questions:

• Business type: local business, SaaS, ecommerce, creator, agency, personal
• Primary email platform: Gmail, Outlook, other
• Compliance regions: US only, EU/GDPR, both
• Brand voice: professional, friendly, casual, authoritative

3. Generate email-profile.md with these settings 4. All sub-skills reference this profile to adapt recommendations

Profile-Driven Behavior

Quality Gates

Hard rules enforced across all sub-skills:

• Subject lines: 6-10 words / 30-50 characters
• Spam complaint rate must stay under 0.1% (hard limit: 0.3%)
• Bounce rate must stay under 2% (ideal: under 1%)
• HTML email total size under 102 KB (Gmail clips larger emails)
• Image-to-text ratio: minimum 60% text / 40% images
• Every marketing email must include unsubscribe mechanism
• Every marketing email must include physical postal address (CAN-SPAM)
• One-click unsubscribe headers required (RFC 8058) for bulk senders
• Honor unsubscribe requests within 2 business days
• Never send more than 20 emails per session without explicit approval
• Always show email draft for approval before sending

Reference Files

Load these on-demand as needed -- do NOT load all at startup:

• references/deliverability-rules.md -- SPF/DKIM/DMARC validation, bulk sender rules
• references/benchmarks.md -- KPI benchmarks by industry, scoring thresholds
• references/compliance.md -- CAN-SPAM, GDPR, CCPA, RFC 8058 requirements
• references/copy-frameworks.md -- PAS, AIDA, BAB, FAB, 4Ps with templates
• references/technical-standards.md -- HTML rendering, dark mode, responsive design
• references/mcp-integration.md -- Setup guides for Gmail, Outlook, SendGrid, etc.

Scoring Methodology

Email Health Score (0-100) -- for /email audit

Email Quality Score (0-100) -- for /email review

Priority Levels

• Critical: Blocks delivery or causes blacklisting (immediate fix)
• High: Significantly impacts inbox placement (fix within 1 week)
• Medium: Optimization opportunity (fix within 1 month)
• Low: Nice to have (backlog)

Sub-Skills

This skill orchestrates 6 specialized sub-skills:

1. email-check -- Inbox triage, importance scoring, reply suggestions 2. email-write -- Email composition with copy frameworks and templates 3. email-review -- Pre-send quality scoring (0-100) 4. email-audit -- Domain deliverability audit (SPF/DKIM/DMARC, blacklists) 5. email-sequence -- Automation sequence design (welcome, nurture, win-back) 6. email-plan -- Email marketing strategy with industry templates

Subagents

For parallel analysis during audits:

• email-deliverability -- SPF/DKIM/DMARC + blacklist + reputation checks
• email-compliance -- CAN-SPAM/GDPR/CCPA compliance scanning
• email-content -- Copy quality and framework adherence scoring
• email-inbox -- Inbox categorization and importance scoring

MCP Integration

Detecting Available MCP Tools

Check for these tool patterns to determine available platforms:

• Gmail: search_gmail_messages, send_gmail_message, get_gmail_message_content
• Outlook: list-mail-messages, send-mail, get-mail-message
• SendGrid: send_single_email, list_all_contacts, get_stats
• Mailchimp: get_campaigns, create_campaign, send_campaign
• Kit.com: kit_list_subscribers, kit_create_broadcast

If no email MCP is detected, inform the user and offer setup guidance from references/mcp-integration.md.

Email Marketing Benchmarks

This reference provides industry-standard KPI benchmarks, thresholds, and performance targets for email campaigns. Use these numbers to score emails, set goals, and identify optimization opportunities.

---

Open Rate Benchmarks by Industry (2025)

Notes:

• CTOR (Click-to-Open Rate) = (Clicks / Opens) × 100 (measures email content quality)
• Open rates are unreliable where Apple Mail Privacy Protection (MPP) is prevalent. MPP pre-fetches all emails, registering 100% opens for Apple Mail users (~50-60% of email opens). True open rates may be significantly lower than reported. Use click rate and CTOR as more reliable engagement metrics.
• Industry benchmarks updated Q1 2025

---

KPI Threshold Tables (For Scoring)

Open Rate Thresholds

Click Rate Thresholds

Click-to-Open Rate (CTOR) Thresholds

Bounce Rate Thresholds

Unsubscribe Rate Thresholds

Spam Complaint Rate Thresholds

Critical Threshold: Spam complaint rate >0.1% triggers ISP blocks. Immediately segment complainers, review content.

---

Revenue Benchmarks

ROI Metrics

E-commerce Metrics

SaaS Metrics

---

Sequence Benchmarks

Welcome Series

Welcome series structure: 1. Immediate: Welcome, set expectations 2. Day 1: Quick win or first value delivery 3. Day 3: Education or use case 4. Day 7: Social proof or case study 5. Day 10: Feature highlight or upgrade path 6. Day 14: Final nudge or transition to regular cadence

Nurture Campaigns

Abandoned Cart

Abandoned cart structure: 1. 1 hour: Simple reminder, product images, CTA 2. 24 hours: Add social proof, review snippet, or scarcity 3. 72 hours: Incentive (discount/free shipping) + urgency

Re-engagement

Re-engagement structure: 1. Day 0: "We miss you" + value reminder 2. Day 7: Incentive or exclusive offer 3. Day 14: Final ask + unsubscribe option (clean list)

---

Deliverability Benchmarks

Sender Reputation Scores

Check sender score: Use tools like Sender Score (Return Path) or Google Postmaster Tools.

List Growth Benchmarks

---

Mobile Benchmarks

Device Usage (2025)

Mobile optimization impact:

• Responsive design: +15% click rate
• Single-column layout: +20% readability
• 44px+ touch targets: -30% accidental clicks

---

Subject Line Benchmarks

High-performing subject line patterns:

• Question format: +10% open rate
• Number-based: +8% open rate ("3 ways to...")
• Curiosity gap: +12% open rate (avoid clickbait)

---

Preheader Text Benchmarks

---

Testing Benchmarks

A/B Test Minimums

Common A/B tests by impact: 1. Subject line: Easiest, +10-30% open rate 2. CTA button: +5-20% click rate 3. Send time: +5-15% open rate 4. Personalization: +10-25% engagement 5. Copy framework: +15-40% conversion

---

Frequency Benchmarks

Fatigue signals:

• Unsubscribe rate >0.2% per email
• Open rate declining >5% week-over-week
• Spam complaints increasing

Optimal send times (US):

• B2C: Tuesday-Thursday, 10am-2pm or 8pm-10pm
• B2B: Tuesday-Thursday, 8am-10am or 1pm-3pm
• E-commerce: Sunday evening (planning week), Thursday (pre-weekend)

---

Scoring Methodology

When scoring emails, use weighted averages:

Note on Open Rates: Due to Apple MPP (see notes above), open rates are increasingly unreliable. When audience has high Apple Mail penetration (>40%), consider shifting open rate weight to click rate or CTOR for more accurate scoring.

Critical Metrics (40%):

• Deliverability (bounce <1%, spam <0.05%): 20%
• Open rate vs industry benchmark: 20%

High Priority (35%):

• Click rate vs industry benchmark: 20%
• CTOR (content quality): 15%

Medium Priority (25%):

• Unsubscribe rate: 10%
• Mobile optimization: 10%
• A/B testing evidence: 5%

Score Calculation Example:

Email scores 80% on deliverability (20 * 0.8 = 16)
Email scores 90% on open rate (20 * 0.9 = 18)
Email scores 70% on click rate (20 * 0.7 = 14)
Email scores 85% on CTOR (15 * 0.85 = 12.75)
Email scores 95% on unsub rate (10 * 0.95 = 9.5)
Email scores 100% on mobile (10 * 1.0 = 10)
Email scores 60% on testing (5 * 0.6 = 3)

Total Score: 16 + 18 + 14 + 12.75 + 9.5 + 10 + 3 = 83.25/100

Score Bands:

• 90-100: Excellent (top 10%)
• 75-89: Good (industry average)
• 60-74: Warning (needs optimization)
• <60: Critical (major issues)

---

Anti-Patterns (Performance Killers)

Use these benchmarks to set realistic goals, identify underperformers, and prioritize optimizations.

<!-- Updated: 2026-02-16 -->

Email Compliance Rules

This reference covers CAN-SPAM, GDPR, CCPA, and RFC 8058 compliance requirements for email marketing.

---

CAN-SPAM Act (United States)

Jurisdiction: United States Applies To: Commercial email messages Enforced By: Federal Trade Commission (FTC)

Core Requirements

1. Accurate Header Information

• From/To/Reply-To must accurately identify sender
• Routing information must be accurate
• Domain name must belong to sender

2. Non-Deceptive Subject Lines

• Subject must reflect email content
• No misleading or false subject lines
• Examples of violations:
• "Re: Your order" (when no prior order exists)
• "Your account suspended" (when not true)
• Subject completely unrelated to content

3. Identify as Advertisement

• Must clearly identify commercial messages
• Disclosure can be in subject or body
• Not required for transactional/relationship messages

4. Physical Postal Address

• Valid physical postal address required
• Can be street address, PO box, or private mailbox (PMB) registered with a commercial mail receiving agency (per USPS regulations)
• Must be current and accurate
• Location: Typically in email footer

5. Unsubscribe Mechanism

• Clear and conspicuous opt-out method
• Must work for at least 30 days after email sent
• Process opt-out within 10 business days
• Cannot charge fee or require additional information beyond email address
• Cannot require login to unsubscribe

6. Third-Party Responsibility

• Sender responsible even if hired third party
• Both advertiser and sender can be held liable

Exemptions (Transactional/Relationship Emails)

• Order confirmations
• Account updates
• Warranty information
• Product recall notices
• Security alerts
• Transaction facilitation

Penalties

• Civil: $51,744 per violation (adjusted for inflation)
• Criminal: Aggravated violations (harvesting, spoofing) can result in imprisonment
• No Cap: Each separate email can be a separate violation

Validation Checklist

• ✅ Accurate From/Reply-To headers
• ✅ Subject line matches content
• ✅ Physical postal address in footer
• ✅ Unsubscribe link present and functional
• ✅ Unsubscribe honored within 10 business days
• ❌ Deceptive subject line
• ❌ Missing physical address
• ❌ No unsubscribe mechanism
• ❌ Unsubscribe requires login/payment

---

GDPR (European Union / UK)

Jurisdiction: EU/EEA member states, UK Applies To: Processing of personal data of EU/UK residents Enforced By: Data Protection Authorities (DPAs)

Legal Bases for Email Marketing

1. Consent (Most Common for B2C)

• Must be freely given, specific, informed, unambiguous
• Affirmative action required (no pre-checked boxes)
• Easy to withdraw as it was to give
• Must keep records of consent (who, when, what they consented to)
• Granular consent for different purposes

2. Legitimate Interest (Common for B2B)

• Must document legitimate interest assessment (LIA)
• Balance sender's interest vs. recipient's rights
• Must offer opt-out
• Appropriate for:
• Existing customer relationships
• B2B cold outreach (soft opt-in)
• Similar products/services to existing customers

3. Contract (Transactional Emails Only)

• Order confirmations
• Shipping notifications
• Account-related messages

Core Requirements

1. Data Minimization

• Only collect necessary personal data
• Don't ask for more than needed
• Delete when no longer needed

2. Transparency

• Privacy notice before/at collection
• Clear explanation of data use
• Identity of data controller

3. Individual Rights

• Right to Access: Provide copy of data on request
• Right to Erasure: Delete data ("right to be forgotten")
• Right to Rectification: Correct inaccurate data
• Right to Portability: Provide data in machine-readable format
• Right to Object: Stop processing for marketing
• Right to Restrict: Limit processing in certain cases

4. Data Security

• Appropriate technical and organizational measures
• Encryption of sensitive data
• Regular security assessments

5. Breach Notification

• Notify DPA within 72 hours of breach
• Notify affected individuals if high risk

6. Data Processing Agreements (DPAs)

• Required with email service providers (ESPs)
• Must specify data processing terms

Consent Requirements

Valid Consent Must Be:

• Freely given: No bundled consent, genuine choice
• Specific: Separate consent for different purposes
• Informed: User understands what they consent to
• Unambiguous: Clear affirmative action
• Withdrawable: Easy to withdraw consent

Invalid Consent Examples:

• Pre-checked boxes
• "By using our site, you consent to marketing emails"
• Bundled with terms and conditions
• Unclear language about data use

Documentation Requirements

• What data is collected
• Why it's collected (purpose)
• Legal basis (consent, legitimate interest, etc.)
• How long it's retained
• Who it's shared with
• Date and method of consent

Penalties

• Tier 1: Up to €10M or 2% of global annual revenue (whichever is higher)
• Tier 2: Up to €20M or 4% of global annual revenue
• Based on: Severity, duration, intent, cooperation, prior violations

Validation Checklist

• ✅ Explicit opt-in consent (or documented legitimate interest for B2B)
• ✅ Privacy notice provided before data collection
• ✅ Consent records documented (who, when, what)
• ✅ Easy unsubscribe mechanism
• ✅ Data processing agreement with ESP
• ✅ Breach notification procedures in place
• ❌ Pre-checked consent boxes
• ❌ No privacy notice
• ❌ Cannot provide consent records
• ❌ Difficult to withdraw consent

---

CCPA/CPRA (California)

Jurisdiction: California, USA Applies To: Businesses meeting thresholds (see below) Enforced By: California Privacy Protection Agency (CPPA)

Applicability Thresholds (Any One)

• Annual gross revenues >$25 million
• Buy/sell personal info of 100,000+ California consumers/households/year
• Derive 50%+ of annual revenue from selling/sharing personal info

Core Consumer Rights

1. Right to Know

• What personal information is collected
• Sources of information
• Purpose of collection/use
• Third parties data is shared with
• Specific pieces of data collected

2. Right to Delete

• Request deletion of personal information
• Exceptions: Complete transaction, detect fraud, comply with legal obligations

3. Right to Opt-Out

• Opt out of sale/sharing of personal information
• "Do Not Sell or Share My Personal Info" link required
• Apply opt-out universally (honor GPC - Global Privacy Control)

4. Right to Correct

• Request correction of inaccurate personal information
• Added by CPRA (2023)

5. Right to Limit Sensitive Data Use

• Limit use/disclosure of sensitive personal information
• Added by CPRA (2023)

6. Right to Non-Discrimination

• Cannot discriminate for exercising rights
• No denial of service, different pricing, lower quality
• Exception: Can offer financial incentive for providing data

Email Marketing Implications

1. Privacy Notice Requirements

• Provide notice at or before data collection
• Explain what data is collected and why
• How long data is retained
• If data is sold/shared

2. Do Not Sell Link

• Required on website if selling/sharing data
• Must honor request within 15 business days
• Apply to all browsers/devices for that consumer

3. Sensitive Personal Information

• Email content may contain sensitive data
• Must allow opt-out of sensitive data use

4. Data Sale Definition

• Sharing data with third parties for consideration
• Includes some ESP integrations (ad networks, data brokers)
• Retargeting pixels may constitute "sale"

Verification Requirements

• Reasonable method to verify consumer identity
• Match data points provided to data on file
• Can request additional information if needed

Response Timeframes

• Right to Know: 45 days (extendable to 90)
• Right to Delete: 45 days (extendable to 90)
• Right to Opt-Out: 15 business days

Penalties

• Civil: $2,500 per violation
• Intentional: $7,500 per violation
• Data Breach: $100-$750 per consumer per incident

Validation Checklist

• ✅ Privacy notice provided before data collection
• ✅ "Do Not Sell" link on website (if selling data)
• ✅ Honor opt-out requests within 15 business days
• ✅ Verify consumer identity for requests
• ✅ Data inventory and mapping complete
• ❌ No privacy notice
• ❌ Discriminate against consumers exercising rights
• ❌ Cannot verify data deletion

---

CASL (Canada's Anti-Spam Legislation)

Jurisdiction: Canada Applies To: Commercial electronic messages (CEMs) sent to or from Canada Enforced By: Canadian Radio-television and Telecommunications Commission (CRTC)

Core Requirements

1. Express Consent Required (Opt-In)

• Must obtain explicit consent before sending commercial emails
• Pre-checked boxes are NOT valid consent
• Must clearly identify the sender and purpose at time of consent
• Consent records must be kept (who, when, how)

2. Implied Consent (Limited Duration)

• Valid for existing business relationships: 2 years from last purchase/transaction
• Valid for existing non-business relationships: 2 years from membership/donation
• Valid for inquiries: 6 months from inquiry
• Must convert to express consent before implied consent expires

3. Required Message Elements

• Sender identification (name, business name)
• Contact information (mailing address, phone/email/web)
• Unsubscribe mechanism (must work for 60 days after sending)
• Process unsubscribe within 10 business days

4. Unsubscribe Mechanism

• Must be functional for at least 60 days after email is sent
• Must be processed within 10 business days
• Cannot require any action beyond sending a reply or visiting a single webpage
• Cannot charge a fee

Penalties

• Individuals: Up to $1M CAD per violation
• Organizations: Up to $10M CAD per violation
• Private Right of Action: Individuals can sue for damages (up to $200 per violation, max $1M per day)

Key Differences from CAN-SPAM

• CASL requires opt-in (CAN-SPAM is opt-out)
• CASL applies to messages sent to Canada (not just from)
• Implied consent has a 2-year expiry (CAN-SPAM has none)
• Higher penalties per violation than CAN-SPAM

Validation Checklist

• ✅ Express consent obtained and documented (or valid implied consent)
• ✅ Sender identification in message (name, address, contact info)
• ✅ Functional unsubscribe mechanism (works 60 days)
• ✅ Unsubscribe honored within 10 business days
• ✅ Consent records maintained (who, when, how)
• ❌ No consent obtained before sending
• ❌ Pre-checked consent boxes
• ❌ Implied consent expired (>2 years since last transaction)
• ❌ Unsubscribe mechanism non-functional

---

RFC 8058: One-Click Unsubscribe

Status: IETF Standard (May 2017) Required By: Google, Yahoo, Microsoft (for bulk senders as of 2024) Applies To: Marketing/promotional emails from bulk senders (5,000+ emails/day)

Required Email Headers

List-Unsubscribe: <https://example.com/unsubscribe?id=UNIQUE_ID>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

Technical Requirements

1. HTTPS URI Required

• Must use HTTPS (not HTTP)
• Cannot use mailto: URIs for one-click
• URI must be unique per recipient

2. POST Request Support

• Endpoint must accept POST requests
• POST body: List-Unsubscribe=One-Click
• Must return 2xx status code on success

3. DKIM Coverage

• DKIM signature must cover both headers:
• List-Unsubscribe
• List-Unsubscribe-Post
• Prevents header forgery

4. Processing Requirements

• Process unsubscribe within 2 business days
• No additional confirmation required from user
• Cannot require login/authentication
• Must unsubscribe from sender, not just list

Example Headers

List-Unsubscribe: <https://example.com/unsub?id=a8b3f2c1>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

DKIM signature must cover both list-unsubscribe and list-unsubscribe-post headers. Server endpoint must accept POST with body List-Unsubscribe=One-Click and return 2xx.

Gmail/Yahoo Enforcement

• Bulk senders (5,000+ emails/day) must implement
• Non-compliance results in:
• Temporary deferral (4xx codes)
• Permanent rejection (5xx codes)
• Lower sender reputation
• Reduced inbox placement

Validation Checklist

• ✅ Both headers present (List-Unsubscribe + List-Unsubscribe-Post)
• ✅ HTTPS URI (not HTTP or mailto)
• ✅ Endpoint accepts POST requests
• ✅ Returns 2xx status code
• ✅ DKIM signature covers both headers
• ✅ Processes unsubscribe within 2 business days
• ❌ Missing List-Unsubscribe-Post header
• ❌ HTTP URI (must be HTTPS)
• ❌ Endpoint returns errors (4xx/5xx)
• ❌ DKIM doesn't cover headers
• ❌ Requires user login/confirmation

---

Compliance Comparison Table

---

Compliance by Email Type

Transactional/Relationship Emails

• CAN-SPAM: Exempt from most requirements (still need accurate headers, address)
• GDPR: Allowed under "contract" legal basis (no consent needed)
• CCPA: Allowed for transaction fulfillment
• CASL: Exempt (transactional messages are not CEMs)
• RFC 8058: Not required (marketing only)

Marketing/Promotional Emails

• CAN-SPAM: All requirements apply
• GDPR: Requires consent or legitimate interest (documented)
• CCPA: Subject to all privacy rights
• CASL: Express consent required (or valid implied consent within 2-year window)
• RFC 8058: Required for bulk senders (5,000+/day)

B2B Cold Outreach

• CAN-SPAM: Allowed (must have opt-out)
• GDPR: Allowed under "legitimate interest" (must document LIA)
• CCPA: Subject to privacy rights if California business contacts
• CASL: Requires consent (implied consent for existing business relationships only)
• RFC 8058: Required if bulk volume

---

Geographic Compliance Strategy

US-Only Audience

• Comply with CAN-SPAM (minimum)
• Add RFC 8058 if bulk sender
• California users: Add CCPA disclosures

Canadian Audience

• CASL compliance required (opt-in, not just opt-out)
• Track implied consent expiry dates (2 years from last transaction)
• Keep consent records (who, when, how)
• Include sender identification and contact info in every email

EU/UK Audience

• GDPR compliance required
• Must obtain explicit consent
• Keep consent records
• Data processing agreement with ESP

North American Audience (US + Canada)

• Apply CASL standards (stricter than CAN-SPAM due to opt-in requirement)
• Segment US vs Canada contacts for consent tracking
• RFC 8058 for bulk senders

Global Audience

• Apply GDPR standards (strictest overall)
• Segment by region for consent/opt-in rules
• Unified privacy policy covering all jurisdictions
• RFC 8058 for bulk senders

---

Common Compliance Violations

High-Risk Violations

1. No unsubscribe link - Violates all regulations 2. Deceptive subject lines - CAN-SPAM violation, FTC enforcement 3. No physical address - CAN-SPAM violation 4. Pre-checked consent boxes - GDPR and CASL violation 5. Purchased email lists - GDPR and CASL violation (no valid consent) 6. No privacy notice - GDPR/CCPA violation 7. Sending to Canada without express consent - CASL violation ($10M CAD penalty)

Medium-Risk Violations

1. Slow unsubscribe processing - >10 days CAN-SPAM, >2 days RFC 8058 2. Unsubscribe requires login - CAN-SPAM violation 3. No consent documentation - GDPR enforcement risk 4. Missing RFC 8058 headers - Delivery issues with Google/Yahoo

Low-Risk Issues

1. Unsubscribe link hard to find - Not illegal but bad practice 2. Vague privacy notice - Legal but not best practice 3. No data processing agreement - GDPR risk if audited

---

Compliance Monitoring Checklist

Pre-Send Validation

• [ ] Physical address in footer (CAN-SPAM)
• [ ] Unsubscribe link present and functional
• [ ] Subject line matches content
• [ ] List-Unsubscribe headers (bulk senders)
• [ ] DKIM covers RFC 8058 headers
• [ ] Consent records available (GDPR)
• [ ] Privacy notice provided (GDPR/CCPA)

Post-Send Monitoring

• [ ] Unsubscribe requests honored within SLA
• [ ] Consent withdrawal processed
• [ ] Data deletion requests fulfilled
• [ ] Complaint rate under 0.1%
• [ ] No spam trap hits

Quarterly Audits

• [ ] Review consent documentation
• [ ] Update privacy notices if practices change
• [ ] Verify ESP data processing agreements
• [ ] Test all unsubscribe mechanisms
• [ ] Review list hygiene practices

<!-- Updated: 2026-02-16 -->

Email Copy Frameworks

This reference provides proven email copywriting frameworks with fill-in templates and examples. Use these frameworks to structure persuasive email content based on the campaign objective.

---

Framework Selection Guide

---

PAS (Problem-Agitate-Solve)

Structure

1. Problem: Identify a specific pain point the reader experiences 2. Agitate: Amplify the emotional or practical consequences of the problem 3. Solve: Present your solution as the resolution

When to Use

• Cold emails (builds empathy before pitching)
• Re-engagement campaigns (reminds of unresolved pain)
• Empathy-driven industries (healthcare, consulting, services)

Template

Subject: [PROBLEM_QUESTION]?

Hi [FIRST_NAME],

[PROBLEM_STATEMENT]. Most [TARGET_AUDIENCE] struggle with [SPECIFIC_PAIN_POINT], and it's costing them [COST_OR_CONSEQUENCE].

Here's what makes it worse: [AGITATION_DETAIL_1]. And when [TRIGGER_EVENT] happens, [NEGATIVE_OUTCOME].

We built [PRODUCT/SERVICE] to solve exactly this. [ONE_SENTENCE_SOLUTION].

[SOCIAL_PROOF_OR_RESULT].

[CLEAR_CTA]

[SIGNATURE]

Example (Local Business)

Subject: Losing customers to Google reviews?

Hi Sarah,

73% of consumers trust online reviews as much as personal recommendations. But if you're a local restaurant owner with under 4 stars on Google, you're losing 3 out of 4 potential customers before they even call.

Here's what makes it worse: negative reviews rank higher than positive ones in Google's algorithm. And when a competitor with 4.5 stars opens down the street, your phone stops ringing.

We built ReviewRocket to solve exactly this. We turn happy customers into 5-star Google reviews in under 60 seconds—no apps, no logins, just a text message.

Our clients see an average of 47 new reviews in the first 90 days.

Can I show you a 2-minute demo this week?

Best,
Daniel

---

AIDA (Attention-Interest-Desire-Action)

Structure

1. Attention: Hook with bold claim, question, or shocking stat 2. Interest: Build curiosity with relevant details 3. Desire: Create emotional want through benefits and social proof 4. Action: Clear, urgent CTA

When to Use

• Promotional emails (sales, discounts, launches)
• Product announcements (new features, releases)
• High-energy campaigns (limited-time offers)

Template

Subject: [BOLD_CLAIM or CURIOSITY_HOOK]

[ATTENTION_GRABBING_OPENING]

[INTERESTING_DETAIL_1]. [INTERESTING_DETAIL_2]. [UNEXPECTED_INSIGHT].

Imagine [ASPIRATIONAL_OUTCOME]. [PAINT_PICTURE_OF_SUCCESS]. [REMOVE_OBJECTION_OR_RISK].

[SOCIAL_PROOF]: [TESTIMONIAL_OR_STAT].

[URGENT_CTA] [DEADLINE_OR_SCARCITY].

[SIGNATURE]

Example (SaaS)

Subject: Ship features 3x faster (without hiring)

Your roadmap is piling up. Your customers are waiting. And your engineering team is drowning in tech debt.

What if you could ship 3x more features without adding headcount? That's what happens when you plug AI pair programming into your workflow. Your devs write less boilerplate, catch bugs before QA, and ship production code in half the time.

Imagine closing your next sprint with everything done—and your team asking for more work. No late nights. No missed deadlines. Just predictable velocity.

Over 4,700 teams use Cursor to hit their goals: "We shipped our Q1 roadmap in 6 weeks" — Sarah Chen, VP Eng @ Lattice.

Start your 14-day free trial today. First 100 signups get Pro free for 3 months.

Try Cursor Free →

Best,
Daniel

---

BAB (Before-After-Bridge)

Structure

1. Before: Describe the current undesirable state 2. After: Paint a vivid picture of the ideal state 3. Bridge: Show how your solution gets them there

When to Use

• Welcome emails (onboarding new users)
• Aspirational campaigns (lifestyle, transformation)
• E-commerce (visual before/after)

Template

Subject: From [BEFORE_STATE] to [AFTER_STATE]

Hi [FIRST_NAME],

Right now, you're [CURRENT_STRUGGLE]. [DETAIL_PAIN_POINT]. [EMOTIONAL_CONSEQUENCE].

But imagine this: [VIVID_AFTER_SCENARIO]. [DETAIL_1]. [DETAIL_2]. [EMOTIONAL_BENEFIT].

Here's how to get there: [SOLUTION_NAME] helps you [MECHANISM]. [STEP_OR_FEATURE_1]. [STEP_OR_FEATURE_2].

[SOCIAL_PROOF_OR_CASE_STUDY].

[CTA]

[SIGNATURE]

Example (E-commerce)

Subject: From cluttered desk to minimalist workspace

Hi Alex,

Right now, your desk is chaos. Cables everywhere. Sticky notes covering your monitor. Coffee rings on yesterday's notebook. You waste 15 minutes every morning just finding your charger.

But imagine this: one sleek desk mat. One wireless charger. One cable organizer. Everything has a place. You sit down, open your laptop, and your mind is clear. No distractions. Just flow.

Here's how to get there: our Minimalist Desk Bundle includes everything you need to transform your workspace in under 10 minutes. Magnetic cable clips keep cords invisible. The vegan leather desk mat protects and unifies. The wireless charging pad eliminates 90% of desktop clutter.

Over 12,000 customers have made the switch: "I didn't realize how much mental clutter my desk created until it was gone" — Jamie L.

Shop the Bundle (25% off) →

Cheers,
Daniel

---

FAB (Features-Advantages-Benefits)

Structure

1. Features: Describe what the product/service does (technical specs) 2. Advantages: Explain why those features matter (performance edge) 3. Benefits: Connect to emotional or practical outcomes (what they gain)

When to Use

• Feature announcements (SaaS, tech products)
• B2B emails (decision-makers need logic + emotion)
• Educational content (explaining complex products)

Template

Subject: [NEW_FEATURE] is live

Hi [FIRST_NAME],

We just launched [FEATURE_NAME]: [ONE_SENTENCE_DESCRIPTION].

**What it does**: [FEATURE_DETAIL_1]. [FEATURE_DETAIL_2]. [TECHNICAL_SPEC].

**Why it matters**: [ADVANTAGE_1 - performance/speed/ease]. [ADVANTAGE_2 - competitive edge].

**What you gain**: [BENEFIT_1 - time saved]. [BENEFIT_2 - money saved]. [BENEFIT_3 - outcome achieved].

[USAGE_EXAMPLE_OR_DEMO].

[CTA]

[SIGNATURE]

---

4Ps (Promise-Picture-Proof-Push)

Structure

1. Promise: Make a bold, specific claim 2. Picture: Visualize the outcome in vivid detail 3. Proof: Back it up with data, testimonials, case studies 4. Push: Drive to action with urgency or incentive

When to Use

• Testimonial-heavy campaigns (trust-building)
• High-ticket sales (B2B, courses, coaching)
• Conversion-focused emails (bottom of funnel)

Template

Subject: [BOLD_PROMISE]

[SPECIFIC_PROMISE_STATEMENT].

Picture this: [VIVID_SCENARIO_1]. [DETAIL_2]. [EMOTIONAL_PAYOFF].

Don't take my word for it:

"[TESTIMONIAL_1]" — [NAME_1, TITLE_1]

[CASE_STUDY_STAT]: [COMPANY_NAME] achieved [RESULT] in [TIMEFRAME].

"[TESTIMONIAL_2]" — [NAME_2, TITLE_2]

[URGENT_CTA]. [DEADLINE_OR_BONUS].

[SIGNATURE]

---

Framework Combinations

Advanced campaigns often blend frameworks:

• PAS → AIDA: Problem hook → excitement build → action
• BAB → 4Ps: Transformation vision → proof stack → urgency
• AIDA → FAB: Attention grab → technical depth → benefit closeout

Choose based on:

• Audience awareness: Cold (PAS) vs Warm (AIDA) vs Hot (4Ps)
• Product complexity: Simple (AIDA) vs Technical (FAB)
• Campaign goal: Awareness (BAB) vs Conversion (4Ps)

---

Anti-Patterns (Avoid)

• Burying the lede: Don't hide the problem/promise in paragraph 3
• Skipping agitation: Problem without consequences = no urgency
• Feature dumping: Features without benefits = "so what?"
• Proof-free promises: Claims without evidence = skepticism
• Weak CTAs: "Learn more" vs "Start your free trial" (specific wins)

---

Testing Frameworks

A/B test frameworks by: 1. Same audience, same offer, different structure 2. Track open (subject), click (body), convert (CTA) 3. Winner becomes control for next test 4. Iterate on winning framework (test variations within structure)

Most campaigns benefit from 2-3 framework tests before settling on a winner.

<!-- Updated: 2026-02-16 -->

Email Deliverability Rules & Thresholds

This reference provides validation rules, thresholds, and best practices for email deliverability.

---

SPF (Sender Policy Framework) Validation

Core Rules

• DNS Lookup Limit: Maximum 10 DNS lookups per SPF record (RFC 7208)
• Warning Threshold: 8+ lookups (approaching limit, flattening recommended)
• Record Limit: Only 1 SPF record allowed per domain (multiple = invalid)
• Syntax: v=spf1 [mechanisms] [qualifiers]

Qualifiers

Common Includes

• _spf.google.com - Google Workspace (3 lookups)
• spf.protection.outlook.com - Microsoft 365 (1 lookup)
• _spf.salesforce.com - Salesforce (2 lookups)
• sendgrid.net - SendGrid (1 lookup)
• _spf.mlsend.com - MailerLite (2 lookups)
• servers.mcsv.net - Mailchimp (1 lookup)

SPF Flattening

When approaching the 10-lookup limit: 1. Replace include: mechanisms with direct IP ranges (ip4: / ip6:) 2. Use SPF flattening services (automated IP range updates) 3. Example: Replace include:_spf.google.com with ip4:35.190.247.0/24 ip4:64.233.160.0/19 4. Warning: Manual flattening requires periodic updates when providers change IPs

Validation Checks

• ✅ Single SPF record exists
• ✅ DNS lookup count ≤ 10
• ✅ Uses -all qualifier (production domains)
• ✅ Includes all authorized sending sources
• ⚠️ 8-9 lookups (consider flattening)
• ❌ Multiple SPF records
• ❌ 10+ lookups (invalid, will fail)

---

DKIM (DomainKeys Identified Mail) Validation

Key Requirements

• Minimum Key Size: 2048-bit (NIST recommended minimum as of 2024)
• Legacy Key Size: 1024-bit (deprecated; still accepted by most providers but upgrade strongly recommended)
• Key Rotation: Every 6-12 months
• Selector Naming: Use descriptive selectors (e.g., google, k1, selector1)

Common Selectors by Provider

Required Header Coverage

DKIM signature MUST cover these headers for bulk senders:

• From
• To
• Subject
• Date
• List-Unsubscribe
• List-Unsubscribe-Post

DKIM Discovery Process

1. Check common selectors: google, default, selector1, selector2, k1, mandrill, dkim 2. Query DNS: dig TXT <selector>._domainkey.<domain> 3. Validate key format: v=DKIM1; k=rsa; p=<public-key> 4. Check key length from public key string

Validation Checks

• ✅ DKIM record exists for active selector
• ✅ Key size ≥ 2048-bit
• ✅ Covers List-Unsubscribe headers (bulk senders)
• ⚠️ Key size 1024-bit (upgrade recommended)
• ⚠️ Key age > 12 months (rotate recommended)
• ❌ Key size < 1024-bit (insecure)
• ❌ Invalid record syntax

---

ARC (Authenticated Received Chain) - RFC 8617

ARC preserves authentication results across mail forwarding hops. When a mailing list or forwarding service relays a message, SPF and DKIM can break. ARC allows the final receiver to validate the chain of custody.

Relevance: Google, Microsoft, and Yahoo use ARC results when SPF/DKIM fail due to forwarding. Not directly configurable by senders — handled by intermediaries (mailing lists, forwarding services). Awareness is important when diagnosing "SPF pass but DMARC fail" scenarios caused by mail forwarding.

---

DMARC (Domain-based Message Authentication) Validation

Rollout Sequence

Progressive enforcement recommended: 1. p=none - Monitor mode (collect reports, no enforcement) 2. p=quarantine - Flag as spam (after monitoring 30+ days) 3. p=reject - Block at SMTP (after quarantine 30+ days)

Required Tags

• p= - Policy for domain (none/quarantine/reject)
• rua= - Aggregate report email (required for monitoring)

Optional Tags

Alignment Modes

• Relaxed (r): Organizational domain match (mail.example.com passes for example.com)
• Strict (s): Exact domain match required

Example DMARC Records

# Monitoring phase
v=DMARC1; p=none; rua=mailto:dmarc@example.com; pct=100; adkim=r; aspf=r

# Quarantine phase
v=DMARC1; p=quarantine; rua=mailto:dmarc@example.com; pct=100; fo=1

# Reject phase (full enforcement)
v=DMARC1; p=reject; rua=mailto:dmarc@example.com; pct=100; sp=reject

Industry Statistics

• 18% of top domains have valid DMARC policies
• 7-8% enforce quarantine or reject
• 2.7x higher inbox placement with full SPF+DKIM+DMARC

Validation Checks

• ✅ DMARC record exists
• ✅ rua= tag present (reporting enabled)
• ✅ p=reject or p=quarantine (enforcing)
• ✅ pct=100 (full coverage)
• ⚠️ p=none (monitoring only, no enforcement)
• ⚠️ pct= < 100 (partial enforcement)
• ❌ No DMARC record
• ❌ Invalid syntax

---

IP Warmup Schedule

For new sending IPs or domains with no sending history:

Warmup Best Practices

• Start with most engaged subscribers (opened last 30 days)
• Maintain consistent daily volume (avoid spikes)
• Monitor complaint rates (<0.1% target)
• Pause warmup if bounce rate >2% or complaint rate >0.2%
• Use dedicated IP for high-volume senders (50K+ emails/month)

---

Sender Reputation Factors

Impact Ranking (Most to Least Critical)

Reputation Score Impact

• Full authentication (SPF+DKIM+DMARC): 2.7x higher inbox placement
• Domain age <30 days: 40-50% lower initial reputation
• Complaint rate >0.3%: Automatic filtering/blocking
• Bounce rate >5%: IP/domain reputation decline
• Engagement decline >30%: Lower priority inbox placement

---

Google/Yahoo/Microsoft Bulk Sender Requirements (2024-2026)

Applies to senders of 5,000+ emails/day to personal accounts (Gmail, Yahoo, Outlook.com).

Mandatory Requirements

1. ✅ SPF authentication passing 2. ✅ DKIM authentication passing (both SPF AND DKIM required) 3. ✅ DMARC policy p=none minimum (must align with SPF or DKIM) 4. ✅ One-click unsubscribe (RFC 8058) for marketing emails 5. ✅ Spam complaint rate under 0.3% 6. ✅ Valid forward DNS (A/AAAA record for sending domain) 7. ✅ Valid reverse DNS (PTR record matching forward DNS) 8. ✅ Honor unsubscribe within 2 business days

RFC 8058 One-Click Unsubscribe

Required headers for bulk marketing emails:

List-Unsubscribe: <https://example.com/unsub?id=UNIQUE_ID>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

Requirements:

• HTTPS endpoint (not HTTP)
• Must accept POST requests (not just GET)
• DKIM signature must cover both headers
• Must process unsubscribe within 2 business days
• Endpoint must return 2xx status code

Enforcement Timeline

• Google: Soft enforcement February 2024; hard enforcement (5xx rejections) November 2025
• Yahoo: Enforced February 2024
• Microsoft: Enforcement began May 5, 2025 (junk foldering, then rejection for non-compliant senders)

Non-Compliance Consequences

• Temporary deferral (4xx codes)
• Permanent rejection (5xx codes)
• Sender reputation decline
• Inbox placement reduction

---

Blacklist Checking

Major Blacklists to Monitor

• Spamhaus ZEN (most impactful)
• Spamhaus DBL (domain-based)
• Barracuda (spam filtering)
• Spamcop (user-reported spam)
• SURBL (URI-based)
• URIBL (URI-based)

Checking Process

# Check IP blacklist
dig +short <reversed-ip>.zen.spamhaus.org

# Check domain blacklist
dig +short <domain>.dbl.spamhaus.org

# Return code 127.0.0.x means listed

Delisting Process

1. Identify root cause (spam complaints, compromised account, etc.) 2. Fix underlying issue 3. Request delisting through blacklist provider 4. Monitor to prevent re-listing

---

MX Record Validation

Requirements

• At least 1 MX record (recommended: 2+ for redundancy)
• Priority values: Lower = higher priority (0-65535)
• MX hostname must resolve to A/AAAA record (not CNAME)
• TLS support required for modern deliverability

Example Validation

dig MX example.com +short
# Expected output:
# 10 mail1.example.com.
# 20 mail2.example.com.

dig A mail1.example.com +short
# Expected: Valid IP address

Checks

• ✅ 2+ MX records (redundancy)
• ✅ All MX hostnames resolve to IPs
• ✅ TLS certificates valid (not expired)
• ⚠️ Single MX record (no redundancy)
• ❌ No MX records
• ❌ MX points to CNAME (invalid)
• ❌ TLS certificate expired/invalid

---

Reverse DNS (PTR) Validation

Requirements

• Sending IP must have PTR record
• PTR must match forward DNS (A/AAAA record)
• Hostname should match mail server identity

Validation Example

# Check PTR for IP 192.0.2.1
dig -x 192.0.2.1 +short
# Expected: mail.example.com.

# Verify forward match
dig A mail.example.com +short
# Expected: 192.0.2.1

Checks

• ✅ PTR record exists
• ✅ Forward/reverse DNS match
• ✅ Hostname matches sending identity
• ❌ No PTR record
• ❌ PTR/forward mismatch

---

Scoring Methodology

Deliverability Health Score (0-100)

Score Ranges

• 90-100: Excellent (all systems green)
• 75-89: Good (minor issues, monitor)
• 60-74: Fair (fix recommended issues)
• 40-59: Poor (deliverability at risk)
• 0-39: Critical (immediate action required)

Priority Levels for Fixes

• Critical: Blocking deliverability (blacklisted, no DKIM, SPF fail)
• High: Reducing inbox placement (DMARC p=none, complaint rate >0.2%)
• Medium: Best practice gaps (single MX, 1024-bit DKIM)
• Low: Optimization opportunities (SPF flattening, key rotation)

<!-- Updated: 2026-02-16 -->

MCP Integration Setup Guide

This guide covers setup for all supported email MCP servers. The email skill auto-detects available tools and adapts functionality accordingly.

Gmail MCP (Primary — Recommended)

Server: taylorwilsdon/google_workspace_mcp Install: uvx workspace-mcp or pip install workspace-mcp

Configuration

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "google-workspace": {
      "command": "uvx",
      "args": ["workspace-mcp"],
      "env": {
        "GOOGLE_OAUTH_CREDENTIALS": "/path/to/credentials.json",
        "GOOGLE_OAUTH_TOKEN": "/path/to/token.json"
      }
    }
  }
}

Setup Steps

1. Google Cloud Console → Create new project 2. APIs & Services → Enable Gmail API 3. OAuth consent screen → Configure (External, test users) 4. Credentials → Create OAuth 2.0 Client ID (Desktop app) 5. Download credentials.json to secure location 6. Run uvx workspace-mcp first time to authorize → generates token.json 7. Update paths in settings.json

Key Tools

Microsoft 365 MCP (Optional)

Server: Softeria/ms-365-mcp-server Install: npm-based

Configuration

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "ms-365": {
      "command": "npx",
      "args": ["-y", "ms-365-mcp-server"],
      "env": {
        "AZURE_CLIENT_ID": "your-client-id",
        "AZURE_TENANT_ID": "your-tenant-id",
        "AZURE_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Setup Steps

1. Azure Portal → App registrations → New registration 2. API permissions → Add permissions:

• Mail.Read
• Mail.Send
• Mail.ReadWrite
• Calendars.Read (optional)

3. Certificates & secrets → New client secret 4. Copy Client ID, Tenant ID, Secret to config

Key Tools

SendGrid MCP (Optional — Marketing/Transactional)

Server: Garoth/sendgrid-mcp Install: Clone repo + npm install

Configuration

{
  "mcpServers": {
    "sendgrid": {
      "command": "node",
      "args": ["/path/to/sendgrid-mcp/index.js"],
      "env": {
        "SENDGRID_API_KEY": "your-api-key"
      }
    }
  }
}

Setup Steps

1. SendGrid Dashboard → Settings → API Keys 2. Create API key with Full Access (or Mail Send + Stats permissions) 3. Copy key to config

Key Tools

Free Tier: 100 emails/day forever

Mailchimp MCP (Optional — Marketing)

Server: mattcoatsworth/mailchip-mcp-server Install: npm-based

Configuration

{
  "mcpServers": {
    "mailchimp": {
      "command": "npx",
      "args": ["-y", "mailchimp-mcp-server"],
      "env": {
        "MAILCHIMP_API_KEY": "your-api-key",
        "MAILCHIMP_SERVER_PREFIX": "us1"
      }
    }
  }
}

Key Tools

Free Tier: 500 contacts, 1000 sends/month

Kit.com / ConvertKit MCP (Optional — Creator)

Server: aplaceforallmystuff/mcp-kit Install: npm-based, requires Node.js 18+

Configuration

{
  "mcpServers": {
    "kit": {
      "command": "npx",
      "args": ["-y", "mcp-kit"],
      "env": {
        "KIT_API_SECRET": "your-api-secret"
      }
    }
  }
}

Key Tools

Subscribers, tags, sequences, broadcasts, webhooks management

Free Tier: Up to 10,000 subscribers

CLI Tools (No MCP Required)

checkdmarc (Deliverability Checks)

pip install checkdmarc
checkdmarc example.com

Returns SPF, DMARC, DKIM validation results

dig (DNS Lookups — Pre-installed)

dig txt example.com                              # SPF record
dig txt _dmarc.example.com                       # DMARC record
dig txt selector._domainkey.example.com          # DKIM record
dig mx example.com                               # MX records

Tool Detection

The email skill auto-detects available platforms by checking for these tool patterns:

Offline Mode

If no email MCP server is detected, the skill operates in offline mode:

Available:

• Email composition and review
• Template creation
• Copy auditing
• Deliverability analysis (via checkdmarc/dig)

Requires MCP:

• Inbox checking
• Sending emails
• Draft creation
• Thread management
• Analytics/reporting

Troubleshooting

MCP Server Not Connecting

# Check Claude Code logs
tail -f ~/.claude/logs/mcp.log

# Test MCP server manually
uvx workspace-mcp  # Should start without errors

Gmail OAuth Expired

Delete token.json and re-run authorization flow:

rm /path/to/token.json
uvx workspace-mcp  # Opens browser for re-auth

Tool Not Found

Use ListMcpResourcesTool to verify available tools:

• Email skill will list detected tools on first run
• Check server name matches expected tool patterns

<!-- Updated: 2026-02-16 -->

Email HTML Technical Standards

This reference provides technical standards for HTML email development, including rendering quirks, responsive design, dark mode, image optimization, and Gmail clipping rules.

---

Email Client Market Share (2025)

Critical takeaway: Design for Apple Mail (majority), test in Gmail (quirky), assume Outlook is broken (it is).

---

HTML Rendering Rules

Layout Architecture

Use table-based layouts only. No Grid, no Flexbox, no modern CSS positioning.

<!-- CORRECT: Table-based layout -->
<table role="presentation" cellspacing="0" cellpadding="0" border="0" width="100%">
  <tr>
    <td align="center" style="padding: 20px;">
      <table role="presentation" cellspacing="0" cellpadding="0" border="0" width="600">
        <tr>
          <td style="padding: 20px; background-color: #ffffff;">
            Email content here
          </td>
        </tr>
      </table>
    </td>
  </tr>
</table>

<!-- WRONG: Flexbox (breaks in Outlook, Gmail) -->
<div style="display: flex; justify-content: center;">
  <div style="width: 600px;">
    Email content here
  </div>
</div>

Required table attributes:

• role="presentation" (accessibility, tells screen readers this is layout, not data)
• cellspacing="0" (removes default spacing)
• cellpadding="0" (removes default padding)
• border="0" (removes default border)
• width attribute (not just CSS) for Outlook

Maximum Width

Implementation:

<table role="presentation" width="600" style="max-width: 600px; width: 100%;">
  <!-- Outlook reads width attribute, modern clients read max-width CSS -->
</table>

Inline CSS (Critical)

All critical CSS must be inline. Gmail strips <style> tags. Use <style> only for media queries (progressive enhancement).

<!-- CORRECT: Inline styles -->
<td style="font-family: Arial, sans-serif; font-size: 16px; line-height: 24px; color: #333333;">

<!-- WRONG: External styles (Gmail strips) -->
<style>
  .body-text { font-family: Arial, sans-serif; }
</style>
<td class="body-text">

Exception: Media queries must be in <style> tags (Outlook ignores, Gmail on mobile reads).

Web-Safe Fonts

Gmail and Outlook have limited font support. Use web-safe fonts or specify fallbacks.

Implementation:

font-family: 'Custom Font', Arial, Helvetica, sans-serif;

Custom fonts via @import or `<link>`: Supported in Apple Mail and some modern clients. Always include web-safe fallback. Not worth the risk for most campaigns.

Color Codes

Use 6-character hex codes: #FF5733 (not #F53 or rgb()). Set bgcolor attribute on <td> as Outlook fallback alongside `style="background-color: ...".

Spacing and Padding

Use padding on `<td>`, not margin on elements. Outlook ignores margins on many elements. Always reset with margin: 0; padding: 0; on headings and paragraphs, then apply padding to the parent <td>.

---

Responsive Design

Mobile-First Statistics

• 70%+ of emails opened on mobile (2025 average)
• 15-second attention span on mobile vs 8 seconds on desktop
• Thumb zone: Bottom 50% of screen is easiest to reach

Breakpoints

Approach: Design for desktop (600px), use media queries to adapt for mobile (single column, larger text, stacked elements).

Media Query Classes

Use @media only screen and (max-width: 600px) with !important overrides:

• .mobile-full-width → width: 100% !important; max-width: 100% !important;
• .mobile-padding → padding: 10px !important;
• .mobile-font-size → font-size: 16px !important; line-height: 24px !important;
• .mobile-hide → display: none !important;
• .mobile-stack → display: block !important; width: 100% !important;

Touch Targets (Critical)

Minimum button size: 44x44px (Apple Human Interface Guidelines). Use <table role="presentation"> with <td> containing an <a> with padding: 14px 28px. Minimum 10px padding around all tappable links.

Font Sizes

Mobile font rule: Minimum 14px for any text, 16px for body (prevents auto-zoom on iOS).

Single-Column Stacking

Desktop two-column layouts must stack on mobile. Use class="mobile-stack" on <td> elements and @media (max-width: 600px) { .mobile-stack { display: block !important; width: 100% !important; } } to make columns stack vertically.

---

Dark Mode Compatibility

Prevalence

• Apple Mail: Automatic dark mode on iOS 13+ and macOS Mojave+
• Gmail: Supports dark mode on Android/iOS
• Outlook: Partial support (converts colors unpredictably)

Estimated usage: 30-40% of emails opened in dark mode (2025).

Three Approaches

1. Media Query Approach (Best)

<style>
  @media (prefers-color-scheme: dark) {
    body {
      background-color: #000000 !important;
      color: #FFFFFF !important;
    }
    .dark-bg {
      background-color: #1C1C1C !important;
    }
    .dark-text {
      color: #E0E0E0 !important;
    }
  }
</style>

Support: Apple Mail, Gmail (iOS/Android), some web clients.

2. Data Attributes (Outlook-Specific)

<div style="background-color: #FFFFFF;" data-ogsc="#1C1C1C" data-ogsb="#FFFFFF">
  <!-- Outlook uses data-ogsc (original background) for dark mode -->
</div>

Attributes:

• data-ogsc: Original background color (dark mode uses this)
• data-ogsb: Original text color

3. Meta Tag (Gmail)

<meta name="color-scheme" content="light dark">
<meta name="supported-color-schemes" content="light dark">

Effect: Tells Gmail to adapt UI chrome (not content) to dark mode.

Design Rules for Dark Mode

Logo Dark Mode Fix

Option 1: Add border: 1px solid #CCCCCC to prevent disappearing on dark backgrounds. Option 2: Use two image tags (.light-logo and .dark-logo) with @media (prefers-color-scheme: dark) to swap between them.

---

Image Optimization

Email Size Limits

Gmail clipping: If HTML exceeds 102KB, Gmail truncates the email and shows "[Message clipped] View entire message" link. This breaks CTAs and harms conversion.

Text-to-Image Ratio

Minimum 60% text, maximum 40% images (by email height, not file size).

Why:

• Spam filters flag image-heavy emails
• Users block images by default (30-40% of recipients)
• Accessibility (screen readers can't read images without alt text)

Image-only emails: Deliverability drops 50%+.

Retina Display Optimization

Save images at 2x resolution, display at 1x via width/height attributes. 2x images are ~3-4x larger — use TinyPNG or ImageOptim to compensate.

Alt Text (Required)

Every image needs alt text.

<img src="product.jpg" alt="Blue running shoes - $79.99" width="300" height="200" style="display: block;" />

Alt text best practices:

• Describe the image for screen readers
• Include key info (price, CTA) if image contains text
• For decorative images, use alt="" (empty, not missing)
• Max 125 characters (screen readers truncate)

Image Blocking

30-40% of recipients block images by default (Gmail, Outlook). Fallback strategies: always include alt text, set bgcolor on image <td>, never put CTA text inside images (use HTML text buttons).

Image Formats

Email-safe formats: JPEG, PNG, GIF. Avoid WebP and SVG (limited support).

Compression

Use TinyPNG, ImageOptim, or Squoosh. Target: <100KB per image, <50KB for logos/icons.

---

Gmail-Specific Rules

Clipping Threshold

Gmail clips emails exceeding 102KB total HTML size. This includes:

• HTML markup
• Inline CSS
• Inline SVG (don't use)
• Base64-encoded images (don't use)

Does NOT include:

• External images (loaded via <img src>)
• External stylesheets (which Gmail strips anyway)

How to check email size: 1. Save final HTML file 2. Check file size in bytes: ls -lh email.html 3. Aim for <60KB, absolute max 90KB (buffer for email client wrapping)

If email exceeds 102KB:

• Remove inline SVG (use PNG instead)
• Minify HTML (remove whitespace, comments)
• Reduce inline CSS (Gmail strips <style> anyway, so move media queries to conditional comments)
• Split into multi-part email (not recommended)

Gmail Style Block Limit

Gmail enforces an 8,192 character limit on `<style>` blocks. If your embedded CSS exceeds this, Gmail strips the entire <style> tag rather than partially rendering it. This is separate from the 102KB clipping threshold.

Mitigation:

• Inline critical CSS on elements (required anyway since Gmail strips <style>)
• Keep <style> blocks under 8,192 characters (for media queries and progressive enhancement)
• Minify CSS (remove comments, whitespace) before sending

Gmail Caching and CSS

Gmail caches images indefinitely — add cache-busting query params (?v=2) for updated images. Gmail strips all <style> and <link> tags (except media queries on mobile apps), so inline all critical CSS.

---

Preheader Text

Preheader text is the snippet shown after the subject line in inbox previews.

Character limits:

• Mobile (Apple Mail): 30-40 characters
• Desktop (Gmail): 80-100 characters
• Outlook: 50-70 characters

Implementation: Use hidden <div> with display: none; max-height: 0px; overflow: hidden; mso-hide: all; immediately after <body>.

Rules: 30-80 characters, expand subject line (don't repeat), include CTA or value prop. +3% open rate vs no preheader.

---

Accessibility Standards

Semantic HTML

Use semantic tags where supported:

• <h1>, <h2> for headings (not <font size="5">)
• <p> for paragraphs
• <a> for links (not <span onclick>)

Note: Outlook renders <h1> as Times New Roman by default. Override:

<h1 style="margin: 0; font-family: Arial, sans-serif; font-size: 28px; font-weight: bold; color: #333333;">
  Heading
</h1>

Role Attribute for Tables

<table role="presentation" cellspacing="0" cellpadding="0" border="0">

Why: Tells screen readers this table is for layout, not data. Without it, screen readers announce "table with 3 columns, 5 rows" (confusing).

Link Descriptiveness

Avoid "click here." Use descriptive link text.

<!-- CORRECT -->
<a href="https://example.com/pricing">View our pricing plans</a>

<!-- WRONG -->
<a href="https://example.com/pricing">Click here</a>

Color Contrast

WCAG AA standard: 4.5:1 contrast ratio for normal text, 3:1 for large text (18px+ or 14px+ bold).

Tools: WebAIM Contrast Checker, Coolors Contrast Checker.

---

Outlook-Specific Hacks

Outlook desktop (Windows) uses Microsoft Word rendering engine (yes, really). This breaks most modern CSS.

Conditional Comments

Use <!--[if mso]>...<![endif]--> to target Outlook-only styles, font overrides, spacing fixes, and content visibility.

VML for Background Images

Outlook doesn't support CSS background-image. Use VML (Vector Markup Language) with v:rect and v:fill type="frame" wrapped in <!--[if mso]> conditional comments. Modern approach: Avoid background images in Outlook entirely. Use solid colors or table bgcolor instead.

---

Testing Checklist

Before sending, test in:

Testing tools:

• Litmus (paid): Tests 90+ clients, screenshots
• Email on Acid (paid): Similar to Litmus
• Testi@ (free): Limited clients, slower
• Manual testing: Send to yourself on 3-5 clients

---

Performance Checklist

• [ ] Total HTML size <60KB (Gmail clipping)
• [ ] Individual images <200KB
• [ ] Text-to-image ratio 60/40 minimum
• [ ] All images have alt text
• [ ] All critical CSS inlined
• [ ] Web-safe fonts used
• [ ] 44x44px minimum touch targets
• [ ] Mobile font size 14px+ (16px for body)
• [ ] Responsive breakpoints at 600px and 480px
• [ ] Dark mode styles defined
• [ ] Preheader text 30-80 characters
• [ ] Tested in Apple Mail, Gmail, Outlook
• [ ] No Grid/Flexbox layouts (tables only)

---

Anti-Patterns (Never Do This)

See the email-write sub-skill for a complete HTML email boilerplate with responsive design, dark mode, and Outlook conditional comments.

<!-- Updated: 2026-02-16 -->