Email Review

# Email Review Sub-Skill

## Purpose

Reviews email content before sending and provides a comprehensive quality score (0-100) across 5 weighted dimensions. Identifies critical issues, suggests improvements, and provides a rewritten version for low-scoring emails.

## When to Activate

- User asks to "review this email"
- User provides email content (subject + body) for feedback
- User requests email quality check or score
- User wants to validate email before sending
- User provides Gmail draft ID for review
- User asks about email deliverability or spam risk

## Input Formats

Accept email content in any of these formats:

1. **Pasted text** - Subject line + body in conversation
2. **File path** - Path to HTML email file
3. **Gmail draft ID** - Fetch via `gmail_get_draft` MCP tool
4. **Raw HTML** - HTML email source code

## Scoring Framework

### Overall Score Calculation

Total score = weighted sum of 5 categories:

| Category | Weight | Focus |
|----------|--------|-------|
| Subject Line | 25% | Length, power words, spam triggers, personalization |
| Copy Quality | 25% | Word count, CTA clarity, framework structure, readability |
| Technical/HTML | 20% | Size, responsiveness, dark mode, alt text, preheader |
| Deliverability | 15% | Spam signals, link count, sender reputation factors |
| Compliance | 15% | CAN-SPAM, unsubscribe, physical address, RFC 8058 |

---

## 1. Subject Line Scoring (25% weight)

**Base Score: 0-100, then weighted at 25%**

### Length Check (0-25 points)
- **Optimal**: 6-10 words OR 30-50 characters = 25 points
- **Acceptable**: 5 or 11 words = 20 points
- **Marginal**: 4 or 12 words = 10 points
- **Poor**: <4 or >12 words = 0 points

### Spam Trigger Detection (-5 points each)
Penalize for each occurrence:
- ALL CAPS words
- Multiple exclamation marks (!!!)
- Phrases: "FREE", "Act Now", "Limited Time", "Guaranteed", "Winner", "Click Here", "Buy Now", "Order Now"
- Excessive punctuation ($$$, ???)

### Power Words (+5 points each, max +15)
Bonus for strategic use of:
- "New", "Exclusive", "Proven", "Secret", "Discover"
- "Ultimate", "Essential", "Complete", "Breakthrough"
- Industry-specific power words

### Personalization (+10 points)
- Contains merge tags like `{{first_name}}` or `{{company}}`
- Behavioral personalization indicators

### Emoji Usage (+5 or -5)
- **1 emoji** = +5 points (increases open rates)
- **2+ emojis** = -5 points (reduces professionalism)
- **No emoji** = 0 points (neutral)

---

## 2. Copy Quality Scoring (25% weight)

**Base Score: 0-100, then weighted at 25%**

### Word Count (0-20 points)
- **150-300 words** = 20 points (optimal)
- **100-149 or 301-400** = 15 points
- **50-99 or 401-500** = 10 points
- **<50 or >500** = 0 points

### CTA Count (0-25 points)
- **1 primary CTA** = 25 points (best conversion)
- **2 CTAs** = 15 points (acceptable)
- **3+ CTAs** = 5 points (diluted focus)
- **0 CTAs** = 0 points (no action path)

### CTA Clarity (0-15 points)
Score based on:
- **15 points**: Action verb + benefit ("Get My Free Guide", "Start Your Trial")
- **10 points**: Generic action ("Learn More", "Download")
- **5 points**: Vague ("Submit", "Click Here")
- **0 points**: No CTA or unclear

### Framework Structure (0-15 points)
Check if email follows proven framework:
- **PAS (Problem-Agitate-Solution)**: 15 points
- **AIDA (Attention-Interest-Desire-Action)**: 15 points
- **BAB (Before-After-Bridge)**: 15 points
- **FAB (Features-Advantages-Benefits)**: 15 points
- **4Ps (Picture-Promise-Proof-Push)**: 15 points
- **No clear structure**: 0 points

### Readability (0-15 points)
- Short paragraphs (2-3 lines max): +5
- Bullet points or numbered lists: +5
- Scannable with subheadings: +5
- No walls of text: +5
- Deduct -5 for each readability issue

### Personalization Beyond Name (0-10 points)
- Behavioral triggers (past purchase, browsing): +5
- Location/timezone awareness: +3
- Industry/role customization: +2

---

## 3. Technical/HTML Scoring (20% weight)

**Base Score: 100, deduct points for violations**

### Total Size (-20 if fail)
- **Must be under 102 KB** (Gmail clips emails over this)
- Check HTML + embedded images (if data URIs)

### Text-to-Image Ratio (-15 if fail)
- **Minimum 60% text / 40% images**
- Image-heavy emails trigger spam filters

### Responsive Design (-10 if fail)
Check for:
- Viewport meta tag: `<meta name="viewport" content="width=device-width">`
- Media queries for mobile breakpoints
- Fluid tables or container widths

### Dark Mode Support (-5 if fail)
Check for:
- `<meta name="color-scheme" content="light dark">`
- CSS with `@media (prefers-color-scheme: dark)`
- Dark mode color overrides

### Alt Text on Images (-5 per missing)
- All `<img>` tags must have `alt` attribute
- Alt text should be descriptive, not just filename

### Table-Based Layout (-5 if fail)
- Email should use `<table>` for layout (HTML email best practice)
- Deduct if using CSS Grid/Flexbox (poor email client support)

### Font Safety (-5 if fail)
- Must use web-safe fonts with fallbacks
- Example: `font-family: Arial, Helvetica, sans-serif;`
- Avoid custom web fonts without fallbacks

### CTA Button Size (-5 if fail)
- Minimum **44x44 pixels** (mobile touch target)
- Check all `<a>` styled as buttons

### Plain-Text Version (-10 if fail)
- Must have plain-text MIME part OR
- Text-only fallback within HTML

### Preheader Text (-5 if missing)
- **30-80 character** preview text
- Located immediately after `<body>` tag
- Often hidden with CSS for HTML view

---

## 4. Deliverability Signals (15% weight)

**Base Score: 100, deduct points for red flags**

### Spam Word Density (-5 per word)
Count occurrences of spam triggers in body:
- "Free", "Winner", "Guarantee", "Risk-free", "Act now"
- "Cash", "Bonus", "Extra income", "Work from home"
- "Unsecured credit", "Viagra", "Pharmacy"

### Link Count (warn at 5+)
- **0-3 links** = 0 penalty
- **4-5 links** = -5 points (warning threshold)
- **6+ links** = -15 points (spam signal)

### Image-Only Email (-20 if fail)
- Emails with **only images and no text** are spam signals
- Must have substantive text content

### Unsubscribe Link (-25 if missing)
- **Required for marketing emails**
- Must be clearly visible and functional
- Check for `<a>` with "unsubscribe" keyword

### Sender Name (-10 if generic)
- Deduct for: "info@", "noreply@", "admin@", "support@"
- Personal or company name preferred

### Link Shorteners (-10 if detected)
- Penalize use of: bit.ly, tinyurl, goo.gl, ow.ly
- Spam filters distrust shortened URLs

---

## 5. Compliance Scoring (15% weight)

**Base Score: 100, deduct points for violations**

### Physical Address (-20 if missing)
- **CAN-SPAM requires postal address**
- Check footer for street address or P.O. Box

### Unsubscribe Mechanism (-25 if missing)
- Must have working unsubscribe link
- Should process within 10 business days (CAN-SPAM)

### Honest Subject Line (-15 if misleading)
- Subject must accurately reflect email content
- No deceptive "Re:" or "Fwd:" if not a reply

### RFC 8058 Headers (-10 if missing for bulk)
For bulk/marketing emails, check for:
```
List-Unsubscribe: <mailto:unsub@example.com>
List-Unsubscribe-Post: List-Unsubscribe=One-Click
```

### Sender Identification (-10 if missing)
- Must clearly state who is sending the email
- Check for "From" name and footer company info

---

## Score Interpretation

| Score | Rating | Status | Recommendation |
|-------|--------|--------|----------------|
| 90-100 | Excellent | ✅ Ready to send | Minor tweaks optional |
| 75-89 | Good | ⚠️ Review suggested | Address medium-priority issues |
| 60-74 | Fair | ⚠️ Fix before sending | Resolve high-priority issues |
| 40-59 | Poor | ❌ Needs rework | Significant changes required |
| 0-39 | Critical | ❌ DO NOT SEND | Major compliance/deliverability issues |

---

## Output Format

Structure the review report as:

1. **Header**: `## Email Quality Review` with overall score, rating, status
2. **Score table**: 5 categories with raw score, weight, and weighted score
3. **Issues Found**: Grouped by severity (Critical/High/Medium/Low) with specific fixes
4. **Detailed Breakdown**: Per-category analysis (subject length/triggers/power words, word count/CTA/framework, HTML size/responsive/dark mode, spam words/links, address/unsubscribe/RFC 8058)
5. **Improved Version** (if score < 75): Rewritten subject line, copy fix recommendations, HTML fixes

Use status badges: ✅ Ready to send (90+), ⚠️ Review suggested (75-89), ⚠️ Fix before sending (60-74), ❌ Needs rework (40-59), ❌ DO NOT SEND (0-39).

---

## Workflow

### Step 1: Intake
Identify input format and extract:
- Subject line
- Body copy (text or HTML)
- HTML source (if applicable)

### Step 2: Run Analysis Scripts (if available)

Check for and execute:
```bash
# Subject line scoring
python scripts/score_subject_line.py --subject "[subject]"

# HTML email analysis
python scripts/analyze_email_html.py --file [path]
```

### Step 3: Manual Scoring

For each category:
1. Start with base score
2. Apply positive adjustments
3. Apply penalties
4. Calculate weighted score

### Step 4: Reference Checks

Consult knowledge files for edge cases:
- `references/technical-standards.md` - HTML/CSS email rules
- `references/compliance.md` - CAN-SPAM, GDPR, CASL requirements
- `references/deliverability-rules.md` - Deliverability scoring and spam signal reference

### Step 5: Generate Report

Format output per template above, ensuring:
- Clear categorization of issues by severity
- Actionable fix recommendations
- Improved version if score < 75

### Step 6: User Confirmation

Ask user if they want to:
- Apply suggested improvements
- Re-review after manual edits
- Send as-is (if score >= 75)

---

## Quality Gates

### Hard Rules (Automatic Failure)

These issues result in "DO NOT SEND" status regardless of total score:

1. **Missing unsubscribe link** (for marketing emails)
2. **Missing physical address** (CAN-SPAM violation)
3. **Email size > 102 KB** (Gmail will clip)
4. **Image-only email** (no text content)
5. **Deceptive subject line** (FTC violation)

---

## Edge Cases

### Gmail Drafts
If user provides draft ID:
1. Use `gmail_get_draft` MCP tool to fetch
2. Extract subject from `payload.headers`
3. Extract HTML body from `payload.parts` (mimeType = text/html)
4. Proceed with normal review

### Plain-Text Emails
If email has no HTML:
1. Skip technical/HTML scoring (default to 80/100)
2. Focus on copy quality, subject line, compliance
3. Adjust weighting: Subject 30%, Copy 35%, Deliverability 20%, Compliance 15%

### Non-English Emails
1. Note language in report
2. Skip spam word detection (English-specific)
3. Focus on structural/technical issues
4. Provide caveats about readability scoring

### Transactional Emails
If email is transactional (receipts, confirmations):
1. Relax compliance rules (unsubscribe not required)
2. Focus on technical delivery and clarity
3. Note in report: "Transactional email - relaxed marketing rules"

---

## Tools Integration

### Available Scripts

Run these scripts from the `scripts/` directory:

**score_subject_line.py**
- Input: `python scripts/score_subject_line.py --subject "Subject line text" --json`
- Output: JSON with length, spam triggers, power words, score
- Use: Auto-score subject line component

**analyze_email_html.py**
- Input: `python scripts/analyze_email_html.py --file path/to/email.html --json`
- Output: JSON with size, responsiveness, alt text, preheader, issues
- Use: Auto-score technical/HTML component

### MCP Tools

**gmail_get_draft**
- Fetch draft email from Gmail by ID
- Extract subject and HTML body

**gmail_send_message**
- Send reviewed email (after user approval)

---

## Examples

**High-scoring email** (92/100): Subject "New guide: 5 proven SEO tactics for 2026" -- 8 words, power word, no spam triggers, 280 words, 1 CTA, responsive HTML, all compliance elements present. Status: Ready to send.

**Low-scoring email** (23/100): Subject "FREE MONEY!!! ACT NOW GUARANTEED WINNER!!!" -- all caps, 4 spam triggers, 50 words, 5 CTAs, missing unsubscribe and address. Status: DO NOT SEND (CAN-SPAM violations).

---

## Notes

- Always run available scripts before manual scoring
- Reference knowledge files for edge cases
- Provide specific, actionable recommendations
- Never approve emails with compliance violations
- Weight user industry context (B2B vs B2C vs transactional)
- Update scoring criteria based on evolving best practices