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 plus the consolidation initiative. The foundation is solid—sending works, templates render, preferences are respected, the messaging gateway bridges email to conversations, and all platform features route through the centralized service.

**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 6.5: Email Consolidation (2026-02-12)
  - Created `@lilith/email-client` shared package
  - Migrated SSO, Platform Admin, Landing to shared client (eliminated 3 standalone nodemailer instances)
  - Added generic `/internal/send/template` and `/internal/send/custom` endpoints
  - Added QA email templates and domain event processor
  - Added merch email templates (approval/rejection)

---

## 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

```typescript
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:

```typescript
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:

```typescript
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:

```typescript
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:

```typescript
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:

```typescript
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](../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:

```typescript
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**: 2026-02-12