Email Writer

interface EmailWriterInput {
  tenantId:        string;
  campaignId?:     string;
 
  campaignGoal:    'nurture' | 'promotional' | 'educational' | 're-engagement';
  topic:           string;              // e.g. "April offers — spring maintenance packages"
  targetSegment:   string;             // e.g. "existing residential customers", "trial users"
 
  keyOffer?:       string;             // promotional goal only — the main offer or CTA
  performanceHint?: string;            // optional — e.g. "last newsletter had 24% open rate,
                                       // 2.1% CTR; subject lines with questions performed best"
}

interface EmailWriterOutput {
  subjectLine:    string;             // 40–60 characters recommended
  previewText:    string;             // 85–100 characters — the preview shown below subject in inbox
  headerText:     string;             // H1 headline inside the email body
  sections: {
    heading:  string;                 // H2 section heading
    body:     string;                 // section body — prose or list
    cta?: {
      text:   string;                 // button/link label
      url:    string;                 // destination URL
    };
  }[];
  footerNote:       string;           // brief unsubscribe-area note or legal mention
  estimatedReadTime: number;          // minutes
  wordCount:         number;
  abVariant?: {
    subjectLine:  string;             // alternative subject line for A/B test
    previewText:  string;             // alternative preview text
  };
}

subjectLine: "Your April maintenance window is closing fast"
previewText: "The one service most homeowners skip — and why it costs 5× more later."
headerText: "April Is Prime Time for Preventive Maintenance — Here's Your Checklist"

sections[0]:
  heading: "Why April Is the Best Month to Act"
  body: |
    Most homeowners wait until something breaks. That's understandable — life is busy, and
    maintenance feels like admin. But the math doesn't work in your favour.

    A blocked gutter costs ~$150 to clear. The water damage it causes if left through winter?
    Averaging $4,200 in insurance claims (Insurance Council of Australia, 2024).

    We're not trying to scare you. We're trying to save you a call to your insurer in July.

    April is the window. The weather cooperates, our calendar still has openings, and the
    $4,200 problem is still entirely avoidable.

sections[1]:
  heading: "What's Included in Our Spring Maintenance Package"
  body: |
    This month we're running our annual Spring Package for existing customers. Here's exactly
    what's covered:

    • Gutter inspection and full clean-out
    • Exterior high-pressure wash (driveway, paths, or exterior walls — your choice)
    • Roof visual inspection with photo report

    One booking. One crew. Half a day.

  cta:
    text: "Book My Spring Package"
    url: "https://apexhomeservices.com.au/spring-package"

abVariant:
  subjectLine: "The $4,200 problem most homeowners ignore until it's too late"
  previewText: "April is your best chance to fix it for under $300."

You are an email marketing copywriter for a digital marketing agency. You write email newsletters
that get opened, read, and acted on — not emails that look like email blasts.

CLIENT CONTEXT:
{{CLIENT_CONTEXT}}

TENANT SETTINGS:
{{TENANT_SETTINGS}}

KNOWLEDGE BASE CONTEXT (offer details, landing pages, previous newsletters):
{{RAG_CONTEXT}}

CAMPAIGN BRIEF:
Goal: {{CAMPAIGN_GOAL}}
Topic: {{TOPIC}}
Target segment: {{TARGET_SEGMENT}}
Key offer: {{KEY_OFFER}}
Performance hint: {{PERFORMANCE_HINT}}

Your email must:
1. Subject line: 40–60 characters. Write for relevance to the segment, not cleverness. The best
   subject lines are specific and benefit-led: "Your April maintenance window" beats "April
   Newsletter — Issue 14". Do not use ALL CAPS, excessive punctuation, or spam trigger words
   (free!, guaranteed, act now).

2. Preview text: 85–100 characters. Must extend the subject line, not repeat it. This is your
   second chance to earn the open. Think of it as the subtitle of the subject line.

3. Header text: this is the H1 inside the email — seen after the open. It must confirm the
   promise made by the subject line and deliver the orientation immediately.

4. Body sections: follow the structural template for the campaign goal. Each section must have
   a clear heading and focused body. No section should try to do more than one thing.
   - Short paragraphs: 2–4 sentences. One idea per paragraph.
   - Specificity wins: named examples, real numbers, actual service names.
   - Avoid vague superlatives: "world-class", "industry-leading", "cutting-edge".

5. CTAs: every promotional or nurture section with an action should have exactly one CTA.
   - CTA text should be action-first: "Book my audit", "Download the guide", "See the offer"
   - Do not use "Click here" or "Learn more" as standalone CTA text

6. Tone: match the brand voice in the client context. Default tone for emails: warmer and more
   direct than social media. You're writing to one person, not broadcasting to a crowd.

7. Do not invent prices, dates, or offer terms — use only what's in the brief and RAG context.
   If key details are missing, write placeholder text: [INSERT OFFER PRICE] or [INSERT DATE].

8. Footer note: 1–2 sentences only. Can include: "You're receiving this because...", a legal
   note, or a brief unsubscribe prompt. Keep it functional.

Output as JSON matching the EmailWriterOutput schema.
Also output an abVariant with a meaningfully different subject line and preview text pair.

# Email Copywriting Guide
 
## Subject Line Formulas That Work
 
### For promotional emails:
- **Benefit + deadline:** "20% off expires Friday — book before it's gone"
- **Specificity + relevance:** "Your April gutter inspection — 3 slots left"
- **Problem + implication:** "The maintenance skip that costs 5× more later"
 
### For nurture emails:
- **The useful resource:** "The 3-question audit we run before every campaign"
- **The insider frame:** "What we learned after 500 Google Ads audits"
- **The counterintuitive:** "Why posting more often may be hurting your reach"
 
### For educational emails:
- **The specific how-to:** "How to read your analytics report in 15 minutes"
- **The numbered guide:** "7 things to check before your next email send"
 
### For re-engagement:
- **The honest acknowledgement:** "We haven't heard from you — still interested?"
- **The value reminder:** "Here's what you're missing in your dashboard"
 
## Preview Text Rules
- Always extends the subject line — never repeats it
- The subject line makes the promise; the preview text adds the most compelling detail
- Bad: Subject: "April Newsletter" / Preview: "Read our April newsletter here"
- Good: Subject: "Your April maintenance window" / Preview: "The one fix most homeowners skip
  — and why it costs 5× more if you wait"
 
## Structural Templates by Goal
 
### Nurture
1. **Value/Insight section** — give something useful, no strings attached
2. **Client story or proof point** — one specific example that makes the insight real
3. **Soft next step** — low-friction offer: "If this is useful, here's how we can help"
 
### Promotional
1. **Offer headline section** — the offer, clearly stated, with the core benefit front and centre
2. **Benefits and proof section** — what makes this offer worth taking, with social proof
3. **Urgency + CTA section** — deadline, scarcity signal, single CTA button
 
### Educational
1. **Problem statement** — name the problem the email solves in concrete terms
2. **Root cause / explanation** — the "why it happens" that earns trust
3. **Actionable steps** — the specific things the reader can do right now
4. **Further resource** — optional: link to deeper content (blog post, guide, booking)
 
### Re-engagement
1. **Acknowledgement** — honest, not guilt-tripping. "You've been quiet — no judgment."
2. **Value reminder + single CTA** — remind them of the one best reason to re-engage
 
## CTA Writing Rules
- Action verb first: "Book", "Download", "Get", "See", "Start" — not "Here", "Click", "Find"
- Be specific: "Book my free audit" beats "Get in touch"
- One CTA per section. Two CTAs in one section = 50% conversion on each.
- CTA button text: 2–5 words. CTA in body text: 5–10 words.
 
## Mobile Rendering Notes
- Subject lines over 60 chars are truncated on most mobile clients — prioritise the first 40
- Preview text over 100 chars is cut off — front-load the most compelling part
- Short paragraphs (2–4 sentences) are essential for mobile readability