# 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

```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**: 2025-12-28