email-lifecycle

Email Lifecycle

Reference

• ID: S-GRO-06
• Category: Growth
• Inputs: company.config.yaml (email section, tech_stack), PRDs, activation-onboarding output
• Outputs: email strategy (standards/email/), per-feature email templates and triggers
• Used by: Growth Agent
• Tool scripts: ./tools/artifact/validate.sh

Purpose

Design and document the complete email lifecycle for a SaaS product -- transactional emails, onboarding sequences, activation triggers, and retention campaigns. This skill produces a reusable email strategy and per-feature email specifications that ensure consistent, mobile-responsive, deliverable email communications.

When to Use

• New product needs its email system designed from scratch
• Feature requires transactional or marketing email touchpoints
• Onboarding sequence needs to be created or improved
• Activation or retention email campaigns are being planned

Procedure

Step 0: Email Provider Check

Read email.provider from company.config.yaml.

If not configured, pause and recommend a provider:

• Resend: Simple API, React Email templates, free tier < 3K emails/month. Best for developers.
• Postmark: Excellent deliverability, transactional-only focus. Best for transactional emails.
• SendGrid: Full-featured, good free tier. Best if you need marketing + transactional.
• Amazon SES: Cheapest at scale, more setup. Best for high-volume senders.

Walk the user through updating company.config.yaml with their choice before proceeding.

Step 1: Load Context

1. Read company.config.yaml for:
   • email.provider (Resend, Sendgrid, Postmark, SES, etc.)
   • email.from_address
   • email.template_engine (react-email, mjml, handlebars, jinja, plain-html)
   • tech_stack.language
   • tech_stack.framework
2. Read activation-onboarding output in artifacts/growth/ if available -- map aha moments to email triggers.
3. Read relevant PRDs to understand feature-specific email needs.

Step 2: Generate Email Strategy

Produce standards/email/email-strategy.md covering the following sections.

Email Types & Purpose:

• Transactional (system-triggered, immediate):

  • Welcome / email verification
  • Password reset
  • Invoice / payment receipt
  • Account changes (plan change, settings update)
  • Security alerts (new login, password changed)

• Onboarding Sequence (time-based drip, 5-7 emails):

  • Day 0: Welcome + single next step
  • Day 1: Getting started guide (path to aha moment)
  • Day 3: Feature highlight (show value they haven't discovered)
  • Day 5: Social proof + use case inspiration
  • Day 7: Check-in (need help?) + upgrade nudge if on free plan

• Activation (behavior-triggered):

  • Re-engage dormant users (no login in 7 days)
  • Milestone celebrations (first project, 10th use, etc.)
  • Upgrade prompts (hitting free tier limits)
  • Feature announcement (new capability relevant to their usage)

• Retention (periodic):

  • Weekly/monthly usage report
  • Tips & tricks based on usage patterns
  • What's new / changelog digest

Template Structure (every email):

• Subject line: max 50 chars, personalized, action-oriented
• Preheader: extends subject, max 90 chars
• Body: hero image/header -> content (2-3 short paragraphs) -> single CTA button -> footer
• Footer: unsubscribe link (required), company info, preference center link
• Mobile-responsive: single column, 14px+ body text, 44px+ tap targets

Send Trigger Architecture:

• Event-driven: user action -> event emitted -> email service receives -> template rendered -> sent
• Queue-based: email jobs added to background queue (reference background-jobs skill)
• Delay handling: scheduled sends use cron or delay queues
• Deduplication: prevent duplicate sends (idempotency key per user+email type+timewindow)

Provider Patterns:

• Resend: API-first, React Email templates, webhook delivery tracking
• Sendgrid: Dynamic templates, marketing + transactional, event webhook
• Postmark: Transactional-focused, message streams, template API
• SES: Raw sending, requires own template rendering, cheapest at scale

Step 3: Per-Feature Email Design

For each feature that has email touchpoints:

1. Identify email touchpoints -- what emails does this feature trigger?
2. Design templates: subject, preheader, body copy, CTA
3. Define send triggers: which user event -> which email
4. Set timing: immediate (transactional), delayed (drip), periodic (digest)
5. Handle preferences: which emails can users opt out of? (transactional emails cannot be opted out of; marketing emails must have unsubscribe)

Step 4: Code Pipeline Integration

Produce implementation guidance:

• Email template directory: src/emails/ (or emails/ at root)
• Per template_engine:
  • react-email: TypeScript components in src/emails/, preview with email dev
  • mjml: MJML templates compiled to HTML, preview in browser
  • handlebars: .hbs templates with variable interpolation
  • jinja: .jinja2 templates for Python backends
  • plain-html: static HTML with {{variable}} placeholders
• Send function pattern: sendEmail(type, recipient, data) wrapper that abstracts the provider
• Queue integration: email send jobs via configured queue (reference background-jobs skill)
• Preview workflow: local rendering for visual QA before sending

Step 5: Testing Strategy

• Render test: every template renders without errors with sample data
• Variable test: all template variables have fallback defaults (no blank fields in sent emails)
• Mobile test: email renders correctly on mobile viewport (320px)
• Deliverability: SPF, DKIM, DMARC configuration guidance for the sending domain
• Unsubscribe test: unsubscribe link works and preference is respected on subsequent sends

Step 6: Verify

• All transactional email types are defined (welcome, password reset, invoice, security alerts)
• Onboarding sequence is 5-7 emails with specific timing and content summaries
• Every template is mobile-responsive
• Unsubscribe link is present on all marketing/retention emails
• Run ./tools/artifact/validate.sh on any produced artifacts

Quality Checklist

• [ ] All transactional email types defined (welcome, password reset, invoice, security alerts)
• [ ] Onboarding sequence has 5-7 emails with specific timing and content
• [ ] Each email has: subject (<50 chars), preheader (<90 chars), single CTA, unsubscribe
• [ ] Send triggers are event-driven with specific event names
• [ ] Template engine matches configured tech stack
• [ ] Queue integration pattern defined for async sends
• [ ] Mobile-responsive template requirements specified
• [ ] Deliverability basics covered (SPF, DKIM, DMARC)