Newsletter Creator

Structured frameworks for creating compelling internal and external newsletters with consistent quality, effective curation, and audience-appropriate tone.

Newsletter Structure

Standard Newsletter Sections

NEWSLETTER LAYOUT:

1. HEADER
   - Newsletter name / brand
   - Edition number and date
   - Tagline or theme for this edition

2. TL;DR / HIGHLIGHTS (above the fold)
   - 3-5 bullet summary of key items
   - Designed for scanners who won't read the full email
   - Each bullet links to the corresponding section

3. FEATURED STORY (1 item)
   - Primary content piece
   - 150-250 words with a clear takeaway
   - Supporting image or graphic
   - CTA: read more, watch, try

4. NEWS & UPDATES (3-5 items)
   - Brief summaries (50-100 words each)
   - Consistent format: headline, summary, link
   - Categorized if applicable

5. CURATED CONTENT (3-5 items)
   - Third-party articles, tools, or resources
   - Brief annotation explaining relevance
   - Source attribution

6. SPOTLIGHT SECTION (1 item, rotating)
   - Team member spotlight, customer story, tool tip
   - Rotates theme each edition
   - Personal and engaging

7. UPCOMING EVENTS / DATES
   - Relevant events, webinars, deadlines
   - Calendar format or simple list

8. FOOTER
   - Unsubscribe / manage preferences
   - Social media links
   - Feedback prompt ("Reply with your thoughts")
   - Archives link

Internal vs External Newsletter Differences

Content Curation Methodology

Curation Workflow

WEEKLY CURATION PROCESS:

COLLECT (ongoing throughout week):
- Save articles to curation tool (Pocket, Raindrop, Notion)
- Tag with categories and relevance score
- Note key quotes or takeaways
- Track sources for diversity

EVALUATE (1 day before send):
- Review all saved items
- Score each on: relevance, timeliness, quality, uniqueness
- Select top items per section
- Verify links still work
- Check for duplicates from prior editions

CURATE (writing day):
- Write brief annotations for each item (why it matters)
- Arrange in priority order
- Write featured story and transitions
- Add editorial perspective where appropriate

REVIEW (before send):
- Proofread all copy
- Test all links
- Preview in email client (desktop + mobile)
- Check accessibility (alt text, contrast)
- Send test to 2-3 reviewers

Content Scoring Matrix

THRESHOLD:
  3.5+: Definite include
  2.5-3.4: Include if space permits
  < 2.5: Skip unless slow news week

Tone and Voice Guidelines

Voice Framework by Audience

INTERNAL NEWSLETTER VOICE:

Personality: Friendly colleague who's well-informed
Tone: Warm, transparent, sometimes playful
Language: First-person plural ("we"), casual contractions
Avoid: Corporate jargon, overly formal language, spin

EXAMPLE:
"Big week for the product team — they shipped the new
dashboard that's been in the works since Q3. If you haven't
tried it yet, you're missing out. Here's a quick walkthrough."

──────────────────────────────────────────────────────

EXTERNAL NEWSLETTER VOICE:

Personality: Trusted industry insider
Tone: Authoritative but approachable, value-focused
Language: Second-person ("you"), professional but not stiff
Avoid: Self-promotion overload, clickbait, assumptions

EXAMPLE:
"This week, three major shifts in the data infrastructure
space caught our attention. Here's what they mean for your
stack — and what to do about it."

Annotation Style Guide

CONTENT ANNOTATION FORMULA:

[HEADLINE] (linked)
[1-2 sentence summary of what it covers]
[1 sentence on why it matters to your audience]

EXAMPLE:
"The State of Developer Experience 2025" (link)
GitHub's annual report surveying 12,000 developers on tooling,
AI adoption, and workflow satisfaction. Worth reading for the
data on how teams are actually using AI coding assistants —
the gap between hype and reality is illuminating.

BAD ANNOTATION:
"The State of Developer Experience 2025" (link)
Check out this report from GitHub.

(No context, no why-it-matters, no reason to click)

Layout and Formatting Best Practices

Email Design Principles

FORMATTING RULES:

WIDTH:
- Max content width: 600px
- Single column preferred (reliable rendering)
- 2-column only for desktop-specific sections

TYPOGRAPHY:
- Body: 16px minimum (mobile readability)
- Headlines: 20-24px
- Line height: 1.5-1.6
- Font: System fonts or web-safe (Arial, Georgia, Helvetica)

IMAGES:
- Width: 100% of container (responsive)
- Alt text on every image
- File size: < 200KB per image
- Use sparingly — many clients block images by default

SPACING:
- Section dividers between major sections
- Generous padding (20px+) between items
- White space > cramped content

MOBILE:
- Test on iOS Mail, Gmail app, Outlook app
- Buttons: minimum 44x44px touch target
- Text should be readable without zooming
- Stack columns vertically on mobile

Template Structure (HTML)

EMAIL TEMPLATE SKELETON:




[HEADER: Logo + Edition Info]

[TL;DR BOX: 3-5 bullet highlights]

[DIVIDER]

[FEATURED STORY: Image + Text + CTA Button]

[DIVIDER]

[NEWS SECTION: 3-5 items, consistent format]

[DIVIDER]

[CURATED LINKS: 3-5 external items with annotations]

[DIVIDER]

[SPOTLIGHT: Rotating section]

[DIVIDER]

[EVENTS: Simple list or calendar]

[FOOTER: Unsubscribe, social, feedback]

Subject Line Optimization

Subject Line Formulas

PROVEN FORMATS:

CURIOSITY: "The one metric most teams get wrong"
NUMBER:    "5 things we learned shipping v3.0"
QUESTION:  "Is your CI pipeline costing you hours?"
NEWS:      "Big changes coming to [product] this quarter"
PERSONAL:  "[Name], your weekly engineering digest"
EMOJI:     "This week in product" (use sparingly, max 1)

CHARACTER LIMITS:
- Ideal: 30-50 characters
- Max: 60 characters (mobile truncation)
- Preheader: extend subject with 40-90 chars of context

A/B TEST PAIRS:
- Short vs. long
- Question vs. statement
- With emoji vs. without
- Specific vs. vague
- Personalized vs. generic

Subject Line Anti-Patterns

AVOID:
- ALL CAPS (looks like spam)
- Excessive punctuation (!!!)
- Misleading or clickbait subjects
- "Newsletter #47" (boring, no reason to open)
- Repeating the same format every week
- Overly long subjects that get truncated

Metrics and Performance Tracking

Key Metrics

Performance Review Template

MONTHLY NEWSLETTER REVIEW:

Edition Stats:
| Edition | Date | Open % | Click % | Unsub % | Top Link |
|---------|------|--------|---------|---------|----------|
| #47     |      |        |         |         |          |
| #48     |      |        |         |         |          |
| #49     |      |        |         |         |          |
| #50     |      |        |         |         |          |

Trends:
- Open rate trend: [up/down/flat]
- Best-performing content type: [___]
- Worst-performing content type: [___]
- Optimal send time (from data): [___]

Actions for Next Month:
- [ ] [specific improvement based on data]
- [ ] [content type to add or remove]
- [ ] [send time or frequency adjustment]

Content Calendar Integration

Editorial Calendar Template

MONTHLY CONTENT CALENDAR:

Week 1: [Theme / Focus]
- Featured: [topic]
- Curated: [2-3 planned sources]
- Spotlight: [team member / customer / tool]

Week 2: [Theme / Focus]
- Featured: [topic]
- Curated: [2-3 planned sources]
- Spotlight: [rotating section type]

Week 3: [Theme / Focus]
- Featured: [topic]
- Curated: [2-3 planned sources]
- Spotlight: [rotating section type]

Week 4: [Theme / Focus]
- Featured: [topic]
- Curated: [2-3 planned sources]
- Spotlight: [rotating section type]

RECURRING SECTIONS:
- Monthly: Industry roundup, metrics review
- Quarterly: Retrospective, reader survey
- Annual: Year in review, predictions

Frequency and Timing Recommendations

Newsletter Quality Checklist

See Also

• Marketing (../marketing/SKILL.md)
• Document Skills: DOCX (../document-skills/docx/SKILL.md)
• Email Systems (../email-systems/SKILL.md)
• Product Management (../product-management/SKILL.md)

---

Supporting file: skills/document-skills/docx/SKILL.md

DOCX creation, editing, and analysis

Overview

A user may ask you to create, edit, or analyze the contents of a .docx file. A .docx file is essentially a ZIP archive containing XML files and other resources that you can read or edit. You have different tools and workflows available for different tasks.

Workflow Decision Tree

Reading/Analyzing Content

Use "Text extraction" or "Raw XML access" sections below

Creating New Document

Use "Creating a new Word document" workflow

Editing Existing Document

• Your own document + simple changes Use "Basic OOXML editing" workflow

• Someone else's document Use "Redlining workflow" (recommended default)

• Legal, academic, business, or government docs Use "Redlining workflow" (required)

Reading and analyzing content

Text extraction

If you just need to read the text contents of a document, you should convert the document to markdown using pandoc. Pandoc provides excellent support for preserving document structure and can show tracked changes:

# Convert document to markdown with tracked changes
pandoc --track-changes=all path-to-file.docx -o output.md
# Options: --track-changes=accept/reject/all

Raw XML access

You need raw XML access for: comments, complex formatting, document structure, embedded media, and metadata. For any of these features, you'll need to unpack a document and read its raw XML contents.

Unpacking a file

python ooxml/scripts/unpack.py <office_file> <output_directory>

Key file structures

• word/document.xml - Main document contents
• word/comments.xml - Comments referenced in document.xml
• word/media/ - Embedded images and media files
• Tracked changes use <w:ins> (insertions) and <w:del> (deletions) tags

Creating a new Word document

When creating a new Word document from scratch, use docx-js, which allows you to create Word documents using JavaScript/TypeScript.

Workflow

1. MANDATORY - READ ENTIRE FILE: Read docx-js.md (~500 lines) completely from start to finish. NEVER set any range limits when reading this file. Read the full file content for detailed syntax, critical formatting rules, and best practices before proceeding with document creation.
2. Create a JavaScript/TypeScript file using Document, Paragraph, TextRun components (You can assume all dependencies are installed, but if not, refer to the dependencies section below)
3. Export as .docx using Packer.toBuffer()

Editing an existing Word document

When editing an existing Word document, use the Document library (a Python library for OOXML manipulation). The library automatically handles infrastructure setup and provides methods for document manipulation. For complex scenarios, you can access the underlying DOM directly through the library.

Workflow

1. MANDATORY - READ ENTIRE FILE: Read ooxml.md (~600 lines) completely from start to finish. NEVER set any range limits when reading this file. Read the full file content for the Document library API and XML patterns for directly editing document files.
2. Unpack the document: python ooxml/scripts/unpack.py <office_file> <output_directory>
3. Create and run a Python script using the Document library (see "Document Library" section in ooxml.md)
4. Pack the final document: python ooxml/scripts/pack.py <input_directory> <office_file>

The Document library provides both high-level methods for common operations and direct DOM access for complex scenarios.

Redlining workflow for document review

This workflow allows you to plan comprehensive tracked changes using markdown before implementing them in OOXML. CRITICAL: For complete tracked changes, you must implement ALL changes systematically.

Batching Strategy: Group related changes into batches of 3-10 changes. This makes debugging manageable while maintaining efficiency. Test each batch before moving to the next.

Principle: Minimal, Precise Edits When implementing tracked changes, only mark text that actually changes. Repeating unchanged text makes edits harder to review and appears unprofessional. Break replacements into: [unchanged text] + [deletion] + [insertion] + [unchanged text]. Preserve the original run's RSID for unchanged text by extracting the <w:r> element from the original and reusing it.

Example - Changing "30 days" to "60 days" in a sentence:

# BAD - Replaces entire sentence
'<w:del><w:r><w:delText>The term is 30 days.</w:delText></w:r></w:del><w:ins><w:r><w:t>The term is 60 days.</w:t></w:r></w:ins>'

# GOOD - Only marks what changed, preserves original <w:r> for unchanged text
'<w:r w:rsidR="00AB12CD"><w:t>The term is </w:t></w:r><w:del><w:r><w:delText>30</w:delText></w:r></w:del><w:ins><w:r><w:t>60</w:t></w:r></w:ins><w:r w:rsidR="00AB12CD"><w:t> days.</w:t></w:r>'

Tracked changes workflow

1. Get markdown representation: Convert document to markdown with tracked changes preserved:

   pandoc --track-changes=all path-to-file.docx -o current.md
   

2. Identify and group changes: Review the document and identify ALL changes needed, organizing them into logical batches:

   Location methods (for finding changes in XML):

   • Section/heading numbers (e.g., "Section 3.2", "Article IV")
   • Paragraph identifiers if numbered
   • Grep patterns with unique surrounding text
   • Document structure (e.g., "first paragraph", "signature block")
   • DO NOT use markdown line numbers - they don't map to XML structure

   Batch organization (group 3-10 related changes per batch):

   • By section: "Batch 1: Section 2 amendments", "Batch 2: Section 5 updates"
   • By type: "Batch 1: Date corrections", "Batch 2: Party name changes"
   • By complexity: Start with simple text replacements, then tackle complex structural changes
   • Sequential: "Batch 1: Pages 1-3", "Batch 2: Pages 4-6"

3. Read documentation and unpack:

   • MANDATORY - READ ENTIRE FILE: Read ooxml.md (~600 lines) completely from start to finish. NEVER set any range limits when reading this file. Pay special attention to the "Document Library" and "Tracked Change Patterns" sections.
   • Unpack the document: python ooxml/scripts/unpack.py <file.docx> <dir>
   • Note the suggested RSID: The unpack script will suggest an RSID to use for your tracked changes. Copy this RSID for use in step 4b.

4. Implement changes in batches: Group changes logically (by section, by type, or by proximity) and implement them together in a single script. This approach:

   • Makes debugging easier (smaller batch = easier to isolate errors)
   • Allows incremental progress
   • Maintains efficiency (batch size of 3-10 changes works well)

   Suggested batch groupings:

   • By document section (e.g., "Section 3 changes", "Definitions", "Termination clause")
   • By change type (e.g., "Date changes", "Party name updates", "Legal term replacements")
   • By proximity (e.g., "Changes on pages 1-3", "Changes in first half of document")

   For each batch of related changes:

   a. Map text to XML: Grep for text in word/document.xml to verify how text is split across <w:r> elements.

   b. Create and run script: Use get_node to find nodes, implement changes, then doc.save(). See "Document Library" section in ooxml.md for patterns.

   Note: Always grep word/document.xml immediately before writing a script to get current line numbers and verify text content. Line numbers change after each script run.

5. Pack the document: After all batches are complete, convert the unpacked directory back to .docx:

   python ooxml/scripts/pack.py unpacked reviewed-document.docx
   

6. Final verification: Do a comprehensive check of the complete document:

   • Convert final document to markdown:

     pandoc --track-changes=all reviewed-document.docx -o verification.md
     

   • Verify ALL changes were applied correctly:

     grep "original phrase" verification.md  # Should NOT find it
     grep "replacement phrase" verification.md  # Should find it
     

   • Check that no unintended changes were introduced

Converting Documents to Images

To visually analyze Word documents, convert them to images using a two-step process:

1. Convert DOCX to PDF:

   soffice --headless --convert-to pdf document.docx
   

2. Convert PDF pages to JPEG images:

   pdftoppm -jpeg -r 150 document.pdf page
   

   This creates files like page-1.jpg, page-2.jpg, etc.

Options:

• -r 150: Sets resolution to 150 DPI (adjust for quality/size balance)
• -jpeg: Output JPEG format (use -png for PNG if preferred)
• -f N: First page to convert (e.g., -f 2 starts from page 2)
• -l N: Last page to convert (e.g., -l 5 stops at page 5)
• page: Prefix for output files

Example for specific range:

pdftoppm -jpeg -r 150 -f 2 -l 5 document.pdf page  # Converts only pages 2-5

Code Style Guidelines

IMPORTANT: When generating code for DOCX operations:

• Write concise code
• Avoid verbose variable names and redundant operations
• Avoid unnecessary print statements

Dependencies

Required dependencies (install if not available):

• pandoc: sudo apt-get install pandoc (for text extraction)
• docx: npm install -g docx (for creating new documents)
• LibreOffice: sudo apt-get install libreoffice (for PDF conversion)
• Poppler: sudo apt-get install poppler-utils (for pdftoppm to convert PDF to images)
• defusedxml: pip install defusedxml (for secure XML parsing)

---

Supporting file: skills/email-systems/SKILL.md

Email Systems

Overview

This skill covers building reliable email systems for web applications, including transactional email sending, template design, deliverability optimization, and inbox placement. It addresses integration with email service providers (Resend, AWS SES, SendGrid, Postmark), building responsive HTML email templates with React Email and MJML, configuring DNS records for deliverability (SPF, DKIM, DMARC), managing email types (transactional, notification, marketing), queue management, and bounce/complaint handling.

Use this skill when sending welcome emails, password resets, order confirmations, notification digests, marketing campaigns, or any system-generated email. Also use when debugging deliverability issues or migrating between email providers.

---

Core Principles

1. Transactional and marketing are different - Transactional emails (password reset, receipt) must arrive instantly and reliably. Marketing emails (newsletter, promo) can be batched and should have unsubscribe links. Never mix them on the same sending domain.
2. HTML email is not web development - Email clients render HTML from 2004. No flexbox, no grid, no modern CSS. Use tables for layout, inline styles, and test across clients. React Email and MJML abstract this pain.
3. Deliverability is earned - SPF, DKIM, and DMARC are table stakes, not guarantees. Maintain low bounce rates (< 2%), low complaint rates (< 0.1%), and warm up new sending domains gradually.
4. Queue everything - Never send email synchronously in a request handler. Queue email sends to avoid blocking user requests and to enable retry on failure.
5. Test before sending - Use Mailtrap or Ethereal in development, preview in multiple clients (Litmus, Email on Acid), and verify every link works.

---

Key Patterns

Pattern 1: React Email Templates with Resend

When to use: Building type-safe, component-based email templates with modern DX and reliable delivery.

Implementation:

// emails/welcome.tsx - React Email template
import {
  Html,
  Head,
  Body,
  Container,
  Section,
  Text,
  Button,
  Img,
  Hr,
  Link,
  Preview,
} from "@react-email/components";

interface WelcomeEmailProps {
  userName: string;
  loginUrl: string;
  guideUrl: string;
}

export function WelcomeEmail({ userName, loginUrl, guideUrl }: WelcomeEmailProps) {
  return (
    <Html lang="en">
      <Head />
      <Preview>Welcome to MyApp, {userName}! Here&apos;s how to get started.</Preview>
      <Body style={styles.body}>
        <Container style={styles.container}>
          <Img
            src="https://myapp.com/logo.png"
            width={120}
            height={36}
            alt="MyApp"
          />

          <Section style={styles.section}>
            <Text style={styles.heading}>Welcome, {userName}!</Text>
            <Text style={styles.text}>
              Thanks for signing up. Your account is ready to go.
              Here are three things to get you started:
            </Text>

            <Text style={styles.listItem}>
              <strong>1. Create your first project</strong> - Click "New Project" on your dashboard.
            </Text>
            <Text style={styles.listItem}>
              <strong>2. Invite your team</strong> - Share your workspace with colleagues.
            </Text>
            <Text style={styles.listItem}>
              <strong>3. Explore the guide</strong> - Learn tips and best practices.
            </Text>

            <Section style={styles.buttonContainer}>
              <Button style={styles.button} href={loginUrl}>
                Go to Dashboard
              </Button>
            </Section>
          </Section>

          <Hr style={styles.hr} />

          <Section style={styles.footer}>
            <Text style={styles.footerText}>
              Need help? Reply to this email or visit our{" "}
              <Link href={guideUrl} style={styles.link}>help center</Link>.
            </Text>
            <Text style={styles.footerText}>
              MyApp, Inc. | 123 Street, City, ST 12345
            </Text>
          </Section>
        </Container>
      </Body>
    </Html>
  );
}

const styles = {
  body: {
    backgroundColor: "#f6f9fc",
    fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif',
  },
  container: {
    backgroundColor: "#ffffff",
    margin: "0 auto",
    padding: "20px 0 48px",
    maxWidth: "600px",
    borderRadius: "8px",
  },
  section: { padding: "0 48px" },
  heading: { fontSize: "24px", fontWeight: "bold" as const, marginBottom: "16px" },
  text: { fontSize: "16px", lineHeight: "26px", color: "#404040" },
  listItem: { fontSize: "15px", lineHeight: "24px", color: "#404040", marginBottom: "8px" },
  buttonContainer: { textAlign: "center" as const, marginTop: "24px", marginBottom: "24px" },
  button: {
    backgroundColor: "#0066ff",
    borderRadius: "6px",
    color: "#ffffff",
    fontSize: "16px",
    fontWeight: "bold" as const,
    textDecoration: "none",
    textAlign: "center" as const,
    display: "inline-block",
    padding: "12px 24px",
  },
  hr: { borderColor: "#e6ebf1", margin: "32px 0" },
  footer: { padding: "0 48px" },
  footerText: { fontSize: "12px", color: "#8898aa", lineHeight: "20px" },
  link: { color: "#0066ff" },
};

// Default props for preview
WelcomeEmail.PreviewProps = {
  userName: "Jane",
  loginUrl: "https://myapp.com/dashboard",
  guideUrl: "https://myapp.com/guide",
} satisfies WelcomeEmailProps;

export default WelcomeEmail;

// lib/email.ts - Email sending service
import { Resend } from "resend";
import { WelcomeEmail } from "@/emails/welcome";
import { PasswordResetEmail } from "@/emails/password-reset";

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

// Type-safe email sending
type EmailTemplate =
  | { template: "welcome"; props: { userName: string; loginUrl: string; guideUrl: string } }
  | { template: "password-reset"; props: { resetUrl: string; expiresIn: string } }
  | { template: "invoice"; props: { invoiceUrl: string; amount: string; dueDate: string } };

const templates: Record<string, React.FC<Record<string, unknown>>> = {
  welcome: WelcomeEmail,
  "password-reset": PasswordResetEmail,
};

const subjects: Record<string, (props: Record<string, unknown>) => string> = {
  welcome: () => "Welcome to MyApp!",
  "password-reset": () => "Reset your password",
  invoice: (p) => `Invoice for $${p.amount}`,
};

async function sendEmail(
  to: string,
  email: EmailTemplate
): Promise<{ id: string }> {
  const Template = templates[email.template];
  const subject = subjects[email.template](email.props);

  const { data, error } = await resend.emails.send({
    from: "MyApp <hello@myapp.com>",
    to,
    subject,
    react: Template(email.props),
  });

  if (error) {
    throw new EmailSendError(error.message, { to, template: email.template });
  }

  return { id: data!.id };
}

export { sendEmail };

Why: React Email provides component-based email templates with TypeScript safety, hot reloading during development, and automatic conversion to email-safe HTML. Resend provides high deliverability, simple API, and React Email integration out of the box. Type-safe template definitions prevent sending emails with missing properties.

---

Pattern 2: Email Queue with Retry Logic

When to use: Any production email sending. Never send email synchronously in a request handler.

Implementation:

// jobs/email.ts - Background email processing
import { Queue, Worker } from "bullmq";
import { Redis } from "ioredis";
import { sendEmail } from "@/lib/email";

const connection = new Redis(process.env.REDIS_URL!, { maxRetriesPerRequest: null });

// Define the email queue
const emailQueue = new Queue("email", {
  connection,
  defaultJobOptions: {
    attempts: 3,
    backoff: {
      type: "exponential",
      delay: 60_000, // 1 min, then 2 min, then 4 min
    },
    removeOnComplete: { age: 7 * 24 * 60 * 60 }, // Keep completed jobs for 7 days
    removeOnFail: { age: 30 * 24 * 60 * 60 }, // Keep failed jobs for 30 days
  },
});

// Queue an email (call this from your application code)
async function queueEmail(
  to: string,
  template: EmailTemplate,
  options?: { delay?: number; priority?: number }
): Promise<string> {
  const job = await emailQueue.add(
    template.template,
    { to, template },
    {
      delay: options?.delay,
      priority: options?.priority ?? 0,
    }
  );
  return job.id!;
}

// Process emails in the background
const emailWorker = new Worker(
  "email",
  async (job) => {
    const { to, template } = job.data;

    try {
      const result = await sendEmail(to, template);
      return result;
    } catch (error) {
      // Log for monitoring
      console.error(`Email send failed (attempt ${job.attemptsMade + 1}/${job.opts.attempts}):`, {
        to,
        template: template.template,
        error: (error as Error).message,
      });
      throw error; // BullMQ will retry based on backoff config
    }
  },
  {
    connection,
    concurrency: 10, // Process 10 emails concurrently
    limiter: {
      max: 100, // Max 100 emails per minute (respect ESP rate limits)
      duration: 60_000,
    },
  }
);

// Listen for permanent failures
emailWorker.on("failed", (job, error) => {
  if (job && job.attemptsMade >= (job.opts.attempts ?? 3)) {
    // All retries exhausted - alert and log
    alertOps(`Email permanently failed: ${job.data.to} - ${error.message}`);
  }
});

export { queueEmail };

// Usage in application code
async function handleUserSignup(user: User) {
  // Create user in database (synchronous, in request)
  await db.user.create({ data: user });

  // Queue welcome email (async, background)
  await queueEmail(user.email, {
    template: "welcome",
    props: {
      userName: user.name,
      loginUrl: `${process.env.APP_URL}/dashboard`,
      guideUrl: `${process.env.APP_URL}/guide`,
    },
  });
}

Why: Queuing emails decouples delivery from user requests. If the email provider is slow or down, user signup still succeeds. Exponential backoff handles transient failures. Rate limiting prevents exceeding ESP quotas. Job retention enables debugging delivery issues.

---

Pattern 3: DNS Configuration for Deliverability

When to use: Setting up a new sending domain or diagnosing deliverability issues.

Implementation:

# SPF Record - Authorize sending servers
# Add to DNS as TXT record on your domain
myapp.com.  TXT  "v=spf1 include:_spf.resend.com include:amazonses.com ~all"

# DKIM Record - Cryptographic email signing
# Provider-specific, usually a CNAME record
resend._domainkey.myapp.com.  CNAME  resend._domainkey.example.com.

# DMARC Record - Alignment policy
# Start with p=none (monitor), move to p=quarantine, then p=reject
_dmarc.myapp.com.  TXT  "v=DMARC1; p=quarantine; rua=mailto:dmarc@myapp.com; pct=100; adkim=s; aspf=s"

# Return-Path / Bounce domain (custom envelope sender)
bounce.myapp.com.  MX  10  feedback-smtp.us-east-1.amazonses.com.
bounce.myapp.com.  TXT  "v=spf1 include:amazonses.com ~all"

// Verify DNS configuration programmatically
import { resolveTxt, resolveCname, resolveMx } from "dns/promises";

async function verifyEmailDNS(domain: string): Promise<Record<string, boolean>> {
  const results: Record<string, boolean> = {};

  // Check SPF
  try {
    const txt = await resolveTxt(domain);
    const spf = txt.flat().find((r) => r.startsWith("v=spf1"));
    results.spf = !!spf;
  } catch {
    results.spf = false;
  }

  // Check DMARC
  try {
    const txt = await resolveTxt(`_dmarc.${domain}`);
    const dmarc = txt.flat().find((r) => r.startsWith("v=DMARC1"));
    results.dmarc = !!dmarc;
  } catch {
    results.dmarc = false;
  }

  // Check DKIM (provider-specific selector)
  try {
    const cname = await resolveCname(`resend._domainkey.${domain}`);
    results.dkim = cname.length > 0;
  } catch {
    results.dkim = false;
  }

  return results;
}

Why: Email authentication (SPF, DKIM, DMARC) proves to receiving mail servers that your emails are legitimate. Without them, emails land in spam. SPF says which servers can send for your domain. DKIM cryptographically signs messages. DMARC tells receivers what to do with unauthenticated email.

---

Pattern 4: Bounce and Complaint Handling

When to use: Maintaining sender reputation and deliverability over time.

Implementation:

// Webhook handler for bounces and complaints (SES/Resend/SendGrid)
async function handleEmailEvent(event: EmailEvent): Promise<void> {
  switch (event.type) {
    case "bounce": {
      const { email, bounceType } = event;

      if (bounceType === "permanent") {
        // Hard bounce - never send to this address again
        await db.emailSuppression.upsert({
          where: { email },
          create: { email, reason: "hard_bounce", suppressedAt: new Date() },
          update: { reason: "hard_bounce", suppressedAt: new Date() },
        });

        // Update user record
        await db.user.updateMany({
          where: { email },
          data: { emailVerified: false, emailBounced: true },
        });
      } else {
        // Soft bounce - retry later, suppress after 3 soft bounces
        const count = await db.emailEvent.count({
          where: { email, type: "soft_bounce", createdAt: { gte: thirtyDaysAgo() } },
        });

        if (count >= 3) {
          await db.emailSuppression.create({
            data: { email, reason: "repeated_soft_bounce", suppressedAt: new Date() },
          });
        }
      }
      break;
    }

    case "complaint": {
      // Spam complaint - suppress immediately
      await db.emailSuppression.upsert({
        where: { email: event.email },
        create: { email: event.email, reason: "complaint", suppressedAt: new Date() },
        update: { reason: "complaint", suppressedAt: new Date() },
      });

      // Remove from all marketing lists
      await db.marketingSubscription.updateMany({
        where: { email: event.email },
        data: { unsubscribedAt: new Date(), reason: "spam_complaint" },
      });
      break;
    }
  }
}

// Check suppression list before sending
async function canSendTo(email: string): Promise<boolean> {
  const suppressed = await db.emailSuppression.findUnique({
    where: { email },
  });
  return !suppressed;
}

Why: ESPs monitor bounce and complaint rates. Exceeding thresholds (bounce > 5%, complaints > 0.1%) triggers sending suspensions. A suppression list prevents sending to known-bad addresses, protecting your sender reputation and ensuring legitimate emails reach inboxes.

---

Email Provider Comparison

---

Anti-Patterns

---

Checklist

• SPF record configured for sending domain
• DKIM signing enabled and verified
• DMARC policy set (start with p=none, escalate to p=quarantine)
• Email templates tested in Gmail, Outlook, Apple Mail, Yahoo
• Emails sent through a queue with retry logic
• Bounce and complaint webhooks configured
• Suppression list checked before every send
• Unsubscribe link present in all notification/marketing emails
• Separate sending domains for transactional vs marketing
• Development environment uses test mode (Mailtrap/Ethereal)
• Rate limiting configured to stay within ESP quotas
• Return-path / bounce domain configured

---

Related Resources

• Skills: authentication-patterns (password reset emails), payment-integration (invoice/receipt emails)
• Skills: event-driven-architecture (email as async event)
• Rules: docs/reference/stacks/react-typescript.md (React Email component patterns)

---

Supporting file: skills/marketing/SKILL.md

Marketing Strategy Expert

Comprehensive marketing frameworks for brand building, customer acquisition, and campaign optimization.

Brand Strategy

Brand Architecture

BRAND ARCHITECTURE MODELS:

BRANDED HOUSE:
- Single master brand
- All products under one umbrella
- Example: Google (Google Maps, Gmail, etc.)
- Pro: Brand equity transfer
- Con: Risk concentration

HOUSE OF BRANDS:
- Independent brand identities
- Parent company invisible
- Example: P&G (Tide, Pampers, Crest)
- Pro: Risk isolation
- Con: No equity leverage

ENDORSED BRANDS:
- Sub-brands with parent endorsement
- Example: Marriott (Courtyard by Marriott)
- Pro: Balance of independence and credibility

SUB-BRANDS:
- Parent-driven with modifiers
- Example: Apple iPhone, iPad, iMac
- Pro: Clear hierarchy, shared equity

Brand Positioning Framework

POSITIONING STATEMENT:
For [target audience]
Who [need/want]
[Brand] is the [category]
That [key benefit]
Because [reason to believe]
Unlike [competitive alternative]

BRAND PYRAMID:
           PURPOSE
          /       \
       VALUES      \
      /             \
   PERSONALITY       \
  /                   \
EMOTIONAL BENEFITS     \
/                       \
FUNCTIONAL BENEFITS      \
/                         \
ATTRIBUTES/FEATURES--------

Brand Health Metrics

Market Research

Research Methodology Selection

Customer Journey Mapping

JOURNEY STAGES:

AWARENESS
- Channels: Advertising, PR, social, content
- Touchpoints: Ads, articles, reviews, WOM
- Emotions: Curiosity, interest
- Metrics: Reach, impressions, awareness

CONSIDERATION
- Channels: Website, search, comparisons
- Touchpoints: Product pages, demos, trials
- Emotions: Evaluation, uncertainty
- Metrics: Traffic, engagement, leads

PURCHASE
- Channels: E-commerce, retail, sales
- Touchpoints: Cart, checkout, contract
- Emotions: Anxiety, excitement
- Metrics: Conversion, AOV, close rate

RETENTION
- Channels: Email, support, community
- Touchpoints: Onboarding, support, updates
- Emotions: Satisfaction, frustration
- Metrics: Retention, NPS, CSAT

ADVOCACY
- Channels: Social, reviews, referrals
- Touchpoints: Sharing, reviews, referrals
- Emotions: Loyalty, enthusiasm
- Metrics: Referral rate, reviews, UGC

Customer Segmentation

Segmentation Approaches

Segmentation Framework

EFFECTIVE SEGMENTS ARE:
- Measurable: Size and characteristics quantifiable
- Substantial: Large enough to be profitable
- Accessible: Can be reached effectively
- Differentiable: Respond differently to marketing
- Actionable: Can design programs for them

SEGMENT PRIORITIZATION:
| Segment | Size | Growth | Profitability | Fit | Priority |
|---------|------|--------|---------------|-----|----------|
| A | | | | | |
| B | | | | | |
| C | | | | | |

Persona Development

PERSONA TEMPLATE:

NAME: [Representative name]
PHOTO: [Stock image]

DEMOGRAPHICS:
- Age, gender, location
- Income, education
- Family status, occupation

PSYCHOGRAPHICS:
- Values and beliefs
- Interests and hobbies
- Media consumption

GOALS & CHALLENGES:
- What they're trying to achieve
- Pain points and frustrations
- Barriers to success

BUYING BEHAVIOR:
- Decision criteria
- Information sources
- Objections and concerns

QUOTE:
"A representative statement that captures their perspective"

Digital Marketing

Channel Strategy

Marketing Funnel Metrics

AWARENESS → INTEREST → CONSIDERATION → PURCHASE → LOYALTY

TOFU (Top of Funnel):
- Impressions
- Reach
- Website visitors
- Social followers

MOFU (Middle of Funnel):
- Leads generated
- MQLs
- Content downloads
- Email subscribers

BOFU (Bottom of Funnel):
- SQLs
- Opportunities
- Conversion rate
- Revenue

POST-PURCHASE:
- Retention rate
- NPS
- Repeat purchase rate
- Referrals

Marketing Technology Stack

CORE SYSTEMS:

CRM: Customer data management
- Salesforce, HubSpot, Dynamics

MAP: Marketing automation
- Marketo, Pardot, HubSpot

CMS: Content management
- WordPress, Adobe Experience Manager

ANALYTICS: Performance measurement
- Google Analytics, Adobe Analytics

CDP: Customer data platform
- Segment, Tealium, Adobe CDP

ADDITIONAL TOOLS:
- Social management (Sprout, Hootsuite)
- SEO tools (SEMrush, Ahrefs)
- Email (Mailchimp, Klaviyo)
- Advertising (Google Ads, Meta)
- Personalization (Optimizely, Dynamic Yield)

Content Strategy

Content Pillars Framework

CONTENT PILLARS:
Strategic themes that align content with brand positioning

PILLAR STRUCTURE:
| Pillar | Audience Need | Business Goal | Content Types |
|--------|---------------|---------------|---------------|
| 1 | | | |
| 2 | | | |
| 3 | | | |

CONTENT MATRIX:
| Stage | Educational | Entertaining | Inspiring | Convincing |
|-------|-------------|--------------|-----------|------------|
| Awareness | Blog posts | Videos | Stories | |
| Consideration | Guides | Webinars | Case studies | Comparisons |
| Decision | | | Testimonials | Demos |

Content Calendar

Marketing Analytics

Marketing Metrics Framework

Attribution Models

Campaign Management

Campaign Planning Template

CAMPAIGN BRIEF:

OBJECTIVE:
- Business goal (revenue, leads, awareness)
- SMART metrics (specific targets)

TARGET AUDIENCE:
- Primary segment
- Secondary segment
- Exclusions

KEY MESSAGE:
- Main proposition
- Supporting messages
- Call to action

CREATIVE REQUIREMENTS:
- Channels and formats
- Assets needed
- Brand guidelines

BUDGET ALLOCATION:
| Channel | Budget | Expected Results |
|---------|--------|------------------|
| | | |

TIMELINE:
- Planning: [dates]
- Creative: [dates]
- Launch: [date]
- Optimization: [dates]
- Wrap-up: [date]

SUCCESS METRICS:
- Primary KPI: [target]
- Secondary KPIs: [targets]

Campaign Optimization

OPTIMIZATION CADENCE:

Daily:
- Budget pacing
- Bid adjustments
- Pause underperformers

Weekly:
- Creative performance
- Audience refinement
- A/B test results

Monthly:
- Channel mix optimization
- Strategy adjustments
- Forecast updates

POST-CAMPAIGN:
- Performance analysis
- ROI calculation
- Learnings documentation
- Next campaign recommendations

PR & Communications

PR Strategy Framework

EARNED MEDIA APPROACH:

PROACTIVE:
- News announcements
- Thought leadership
- Executive visibility
- Industry awards

REACTIVE:
- Media inquiries
- Crisis response
- Issues management
- Rapid response

MEASUREMENT:
- Media impressions
- Share of voice
- Message pull-through
- Sentiment analysis

Crisis Communication

RESPONSE PROTOCOL:

ASSESS (0-1 hour):
- Confirm facts
- Assess severity
- Notify leadership
- Activate team

RESPOND (1-4 hours):
- Holding statement
- Internal communication
- Social monitoring
- Media inquiries

MANAGE (ongoing):
- Regular updates
- Stakeholder outreach
- Narrative control
- Documentation

RECOVER (post-crisis):
- After-action review
- Reputation repair
- Process improvement

See Also

• Sales (../sales/SKILL.md)
• Product Management (../product-management/SKILL.md)
• Data Science (../data-science/SKILL.md)

---

Supporting file: skills/product-management/SKILL.md

Product Management Expert

Comprehensive product frameworks for strategy, roadmapping, prioritization, and product-market fit.

Product Strategy

Product Vision Framework

VISION COMPONENTS:

TARGET CUSTOMER:
- Who are we building for?
- What segments? What personas?

CUSTOMER NEED:
- What problem are we solving?
- What job to be done?

KEY BENEFIT:
- Primary value proposition
- Why customers will choose us

DIFFERENTIATOR:
- What makes us unique?
- Competitive advantage

AMAZON PRESS RELEASE FORMAT:
- Headline
- Summary (who, what, when, where, why)
- Problem statement
- Solution description
- Customer quote
- How to get started

Product-Market Fit

PMF INDICATORS:

QUANTITATIVE:
- 40%+ would be "very disappointed" without product (Sean Ellis)
- Strong organic growth/referrals
- Low churn, high retention
- Improving unit economics

QUALITATIVE:
- Customers actively advocating
- Word of mouth driving acquisition
- Pull from market (not push)
- Customers expanding usage

PMF SURVEY:
"How would you feel if you could no longer use [product]?"
- Very disappointed → Target 40%+
- Somewhat disappointed
- Not disappointed

PMF STAGES:
1. Problem-Solution Fit: Validated problem worth solving
2. Product-Market Fit: Solution resonates with market
3. Business Model Fit: Sustainable economics
4. Scale: Growth mechanics work

Jobs to Be Done (JTBD)

JOB STATEMENT:
When [situation], I want to [motivation], so I can [expected outcome].

FORCES OF PROGRESS:
Push: Current pain/frustration
Pull: Attraction to new solution
Anxiety: Concerns about switching
Habit: Comfort with status quo

See Customer Research Methods (./references/customer-research-methods.md) for detailed JTBD methodology and interview techniques.

Roadmap Planning

Roadmap Types

OKR Framework for Product

PRODUCT OKR STRUCTURE:

OBJECTIVE: [Qualitative goal]

KEY RESULT 1: [Metric] from [X] to [Y]
KEY RESULT 2: [Metric] from [X] to [Y]
KEY RESULT 3: [Metric] from [X] to [Y]

EXAMPLE:
O: Become the preferred solution for enterprise customers
KR1: Increase enterprise NPS from 40 to 60
KR2: Reduce enterprise churn from 8% to 4%
KR3: Increase enterprise ACV from $50K to $75K

Feature Prioritization

RICE Framework

RICE SCORE = (Reach x Impact x Confidence) / Effort

REACH: How many customers affected per quarter
- Count: Number of users, customers, transactions

IMPACT: Effect on individual customer
- 3 = Massive
- 2 = High
- 1 = Medium
- 0.5 = Low
- 0.25 = Minimal

CONFIDENCE: How sure are we
- 100% = High confidence
- 80% = Medium
- 50% = Low

EFFORT: Person-months of work
- Engineering time
- Design time
- PM time

EXAMPLE:
| Feature | Reach | Impact | Conf | Effort | RICE |
|---------|-------|--------|------|--------|------|
| A | 5000 | 2 | 80% | 3 | 2667 |
| B | 1000 | 3 | 100% | 1 | 3000 |
| C | 10000 | 1 | 50% | 5 | 1000 |

ICE Framework

ICE SCORE = Impact x Confidence x Ease

IMPACT (1-10):
How much will this move our key metric?

CONFIDENCE (1-10):
How sure are we about impact estimate?

EASE (1-10):
How easy to implement?

Note: Simpler than RICE, good for quick decisions

MoSCoW Method

Kano Model

CATEGORIES:

BASIC (Must-be):
- Expected features
- Absence causes dissatisfaction
- Example: Login functionality

PERFORMANCE (Linear):
- More is better
- Satisfaction proportional to fulfillment
- Example: Speed, capacity

DELIGHTERS (Excitement):
- Unexpected features
- Absence doesn't cause dissatisfaction
- Presence greatly increases satisfaction
- Example: Innovative features

Customer Research

Research Methods

See Customer Research Methods (./references/customer-research-methods.md) for detailed interview frameworks, persona templates, and usability testing protocols.

Product Analytics

Key Metrics Framework

PIRATE METRICS (AARRR):

ACQUISITION:
- How do users find us?
- Metrics: Traffic, signups, installs

ACTIVATION:
- First positive experience
- Metrics: Onboarding completion, first value

RETENTION:
- Do they come back?
- Metrics: DAU/MAU, cohort retention

REVENUE:
- Do they pay?
- Metrics: Conversion, ARPU, LTV

REFERRAL:
- Do they tell others?
- Metrics: NPS, referral rate, viral coefficient

Product Health Metrics

See Analytics and Experimentation (./references/analytics-and-experimentation.md) for detailed cohort analysis, retention benchmarks, and event tracking strategies.

A/B Testing

Experiment Framework

EXPERIMENT DESIGN:

HYPOTHESIS:
If we [change], then [metric] will [improve/decrease] because [rationale].

METRICS:
- Primary: The metric you're trying to move
- Secondary: Other metrics to monitor
- Guardrails: Metrics that shouldn't degrade

SAMPLE SIZE:
Use calculator based on:
- Baseline conversion rate
- Minimum detectable effect (MDE)
- Statistical significance (usually 95%)
- Power (usually 80%)

DURATION:
- At least 1 business cycle
- Adequate sample size
- Account for novelty effects

Decision Framework

• Ship: Stat sig + practical sig + no negative guardrails
• Iterate: Directionally positive but not stat sig, or mixed results
• Kill: No effect or negative impact
• Investigate: Unexpected results, large variance, segment differences

See Analytics and Experimentation (./references/analytics-and-experimentation.md) for detailed statistical concepts, common pitfalls, and segmentation analysis.

Product Launches

Launch Checklist

PRE-LAUNCH:
- [ ] Feature complete and tested
- [ ] Documentation ready
- [ ] Support team trained
- [ ] Marketing materials prepared
- [ ] Sales team enabled
- [ ] Beta feedback incorporated
- [ ] Success metrics defined

LAUNCH:
- [ ] Staged rollout plan
- [ ] Monitoring dashboards live
- [ ] War room established
- [ ] Communication sent
- [ ] Feature flags enabled

POST-LAUNCH:
- [ ] Monitor metrics and feedback
- [ ] Address critical issues
- [ ] Gather early learnings
- [ ] Celebrate wins
- [ ] Retrospective scheduled

Go-to-Market Plan

Product Discovery

Discovery Techniques

Opportunity Assessment

OPPORTUNITY CANVAS:

PROBLEM:
What problem are we solving?
Who has this problem?
How do they solve it today?

EVIDENCE:
What data supports this?
Customer quotes/feedback?
Market research?

SOLUTION:
What are we proposing?
Why will it work?
What's the MVP?

ASSUMPTIONS:
What must be true?
What risks exist?
How will we validate?

OUTCOME:
Success metrics?
Business impact?
Customer impact?

Deliverable Templates

PRD Structure (One-Pager)

1. EXECUTIVE SUMMARY (3-4 sentences)
- What: One-line description
- Why: Core problem being solved
- Who: Target users
- Success: How we'll measure it

2. BACKGROUND & CONTEXT
- Current situation and pain points
- Supporting data
- Strategic alignment

3. GOALS & SUCCESS METRICS
- Primary goal and success metric
- Secondary goals and metrics
- Guardrail metrics

4. USER STORIES
Format: "As a [persona], I want to [action], so that [benefit]"
- Acceptance criteria
- Priority (Must/Should/Could Have)

5. SOLUTION OVERVIEW
- High-level description
- Key user flows
- Out of scope

6. DESIGN & TECHNICAL CONSIDERATIONS
- Mockups/wireframes
- Dependencies
- Scalability

7. LAUNCH PLAN
- Rollout strategy
- Success criteria
- Risk mitigation

8. OPEN QUESTIONS
- Unresolved decisions
- Areas needing research

Additional Resources

For comprehensive product management frameworks and methodologies:

• Product Strategy Expert (./references/product-strategy-expert.md) - Complete PM reference guide
• Customer Research Methods (./references/customer-research-methods.md) - Interview frameworks, personas, usability testing
• Analytics and Experimentation (./references/analytics-and-experimentation.md) - Retention analysis, A/B testing, event tracking

See Also

• Data Science (../data-science/SKILL.md) - Analytics and ML
• Marketing (../marketing/SKILL.md) - Go-to-market strategy
• Business Strategy (../business-strategy/SKILL.md) - Strategic planning