platform-codebase/features/email/docs/ROADMAP.md

Email Service Roadmap

What's coming next for the Lilith email service.

---

Current State

The email service has completed its core infrastructure phases. The foundation is solid—sending works, templates render, preferences are respected, and the messaging gateway bridges email to conversations.

Completed Phases:

• Phase 1: Core Infrastructure (sending, queuing, logging)
• Phase 2: Address Management (creator addresses, aliases)
• Phase 3: User Preferences (categories, unsubscribe flow)
• Phase 4: Admin Interface (dashboard, logs, templates)
• Phase 5: Messaging Gateway (email ↔ conversation)
• Phase 6: User Account Emails (welcome, verification, security)

---

Phase 7: Order Emails

Status: Planned

The next major milestone is integrating with the payments and orders system.

Templates to Create

Template	Trigger	Priority
order-confirmation	Purchase completed	High
order-shipped	Shipping label created	High
order-delivered	Delivery confirmed	Normal
order-refunded	Refund processed	High
order-issue	Problem with order	High
subscription-renewed	Recurring payment success	Normal
subscription-failed	Payment failed	High
subscription-cancelled	User cancelled	Normal

Integration Points

• Payments Service: Listen for payment events
• Shipping Provider: Webhook for tracking updates
• Subscription System: Recurring billing events

Technical Requirements

interface OrderEmailService {
  sendOrderConfirmation(order: Order): Promise<void>;
  sendShippingUpdate(order: Order, tracking: TrackingInfo): Promise<void>;
  sendDeliveryConfirmation(order: Order): Promise<void>;
  sendRefundNotification(order: Order, refund: Refund): Promise<void>;
  sendOrderIssue(order: Order, issue: IssueDetails): Promise<void>;
}

---

Phase 8: Employee & Internal Emails

Status: Planned

Internal communication for platform operations and moderation.

Templates to Create

Template	Recipients	Frequency
new-submission-alert	Moderators	Real-time
daily-digest	Operations team	Daily
weekly-report	Leadership	Weekly
security-alert	Security team	Real-time
system-notification	DevOps	As needed
payout-processed	Finance	Daily

Digest System

Build a scheduled digest system:

interface DigestService {
  // Collect events throughout the day
  recordEvent(type: string, data: any): void;

  // Generate and send digests on schedule
  sendDailyDigest(): Promise<void>;
  sendWeeklyReport(): Promise<void>;
}

Digest Contents:

• New creator signups
• Revenue summary
• Content moderation queue status
• System health metrics
• Upcoming scheduled maintenance

---

Future Enhancements

These are capabilities that would meaningfully improve the service but aren't yet scheduled.

Email Analytics

Understanding how emails perform:

Metric	Implementation
Open Rate	Tracking pixel (opt-in only)
Click Rate	Link wrapping with redirect
Reply Rate	Gateway already tracks this
Unsubscribe Rate	Already logged

Privacy-First Approach:

• Tracking disabled by default
• Admin opt-in per template category
• No tracking for security emails
• Aggregate data only (no individual tracking)

A/B Testing

Test template variations:

interface ABTest {
  templateName: string;
  variants: TemplateVariant[];
  splitRatio: number; // 50/50 default
  metric: 'open' | 'click' | 'reply';
  duration: number; // days
}

Use Cases:

• Subject line testing
• CTA button copy
• Email length experiments
• Send time optimization

Smart Send Timing

Learn when individual users are most likely to engage:

interface SendTimeOptimization {
  // Analyze user's historical engagement
  getOptimalSendTime(userId: string): Date;

  // Queue email for optimal time
  queueForOptimalDelivery(email: QueuedEmail): void;
}

Factors to Consider:

• Historical open times
• User's timezone
• Day of week patterns
• Category-specific patterns

Rich Email Composer

WYSIWYG editor for non-technical admins:

• Drag-and-drop block builder
• Pre-built component library
• Mobile preview
• Brand color picker
• Image upload with CDN hosting

Attachment Support

Enable file attachments in transactional emails:

Use Case	Example
Order receipts	PDF invoice attached
Digital products	Delivery of purchased files
Contracts	Legal documents

Implementation Notes:

• Size limits (10MB per attachment)
• Virus scanning integration
• S3 storage for large files
• Link expiration for security

Email Campaigns

Bulk sending for marketing:

interface Campaign {
  name: string;
  template: string;
  audience: AudienceFilter;
  schedule: Date | 'immediate';
  throttle: number; // emails per minute
}

Safety Features:

• Preview with sample audience
• Gradual rollout (10% → 50% → 100%)
• One-click abort
• Automatic unsubscribe enforcement

SMS Fallback

When email fails, try SMS:

interface FallbackConfig {
  enableSmsForCategories: ['security', 'orders'];
  smsProvider: 'twilio' | 'vonage';
  attemptEmailFirst: true;
  smsDelayMinutes: 15; // wait before SMS fallback
}

Priority Triggers:

• Password reset (critical)
• Login alerts (security)
• Order issues (time-sensitive)
• Payment failures (actionable)

---

Technical Debt

Items to address for long-term health:

Testing Coverage

Current state: ~40% backend, 0% frontend

Target: 80% across all packages

See TEST_PLAN.md for comprehensive testing strategy.

Template Migration

Move templates from filesystem to database:

• Currently: Handlebars files in templates/
• Target: Database-stored with version history
• Benefit: Admin editing without deploys

Queue Monitoring

Add better observability:

• Bull dashboard integration
• Prometheus metrics export
• PagerDuty alerting for queue failures
• Grafana dashboards for email health

Address Verification

Validate addresses before accepting:

interface AddressVerification {
  // Check if email is deliverable
  verifyDeliverability(email: string): Promise<VerificationResult>;

  // Periodic re-verification of stored addresses
  revalidateAddresses(): Promise<void>;
}

Prevents:

• Bounce rate increases
• Sender reputation damage
• Wasted resources on dead addresses

---

Integration Opportunities

With Identity Service

• Automatic preference creation on signup
• Profile data enrichment for templates
• Single sign-out across email sessions

With Payments Service

• Order email triggering
• Subscription lifecycle emails
• Payout notifications for creators

With Moderation Service

• Content removal notifications
• Appeal submission confirmations
• Decision notifications

With Analytics Service

• Email engagement tracking
• User journey attribution
• Conversion funnel analysis

---

Timeline Estimates

Phase	Scope	Complexity
Phase 7: Order Emails	8 templates, payments integration	Medium
Phase 8: Employee Emails	6 templates, digest system	Medium
Email Analytics	Tracking infrastructure, dashboards	High
A/B Testing	Variant system, statistical analysis	High
Rich Composer	WYSIWYG builder, component library	High
SMS Fallback	Provider integration, routing logic	Medium

---

Principles for Future Development

As the email service evolves, these principles guide decisions:

1. Privacy by Default: New features default to privacy-preserving options. Tracking requires explicit enablement.

2. Creator Control: Features should give creators more control over their communication, not less.

3. Simplicity for Users: Email preferences should be understandable by anyone. No dark patterns.

4. Reliability Over Features: A simple email that delivers is better than a fancy email that bounces.

5. Platform Independence: Avoid lock-in to specific email providers. Abstract integrations behind interfaces.

---

Contributing

To propose a new email feature:

1. Check if it aligns with the principles above
2. Consider privacy implications
3. Estimate complexity and dependencies
4. Create a proposal in the platform planning repository

The email service is critical infrastructure. Changes should be deliberate and well-tested.

---

Last Updated: 2025-12-28