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

Email Service Capabilities

A complete breakdown of what the Lilith email service can do today.

---

Core Email Infrastructure

Email Sending

The service handles all outbound email through a unified pipeline:

Method	Use Case	Latency
Immediate Send	Security alerts, password resets	<2 seconds
Queued Send	Order confirmations, notifications	5-30 seconds
Scheduled Send	Digests, campaigns	At scheduled time

Technical Details:

• Nodemailer transport with connection pooling
• Automatic retry (3 attempts with exponential backoff)
• Dead letter queue for permanently failed emails
• Rate limiting per recipient and globally

Template Rendering

All emails use Handlebars templates with a consistent base layout:

{{!-- templates/users/welcome.hbs --}}
<h1>Welcome to Lilith, {{name}}</h1>
<p>Your journey begins here.</p>
<a href="{{verificationUrl}}">Verify your email</a>

Template Features:

• Variable injection with auto-escaping
• Conditional blocks ({{#if}}, {{#unless}})
• Iteration ({{#each}})
• Partials for reusable components
• Base layout wrapper with consistent branding

Email Logging

Every email is tracked through its lifecycle:

queued → sending → sent → delivered → opened (optional)
                      ↓
                   bounced/failed

Log Data Captured:

• Recipient (email, user ID)
• Category and template name
• Subject line
• Status with timestamps
• Error messages (if failed)
• Metadata (template variables, tracking IDs)

---

Email Address Management

Creator Addresses

Creators can claim personalized email addresses:

Feature	Description
Custom Local Part	aurora, midnight.rose, shop
Platform Domain	@inbox.lilith.gg
Display Name	Unicode supported: "Aurora ✨"
Primary Flag	One address designated as primary
Forwarding	Optional forward to external email
Auto-Reply	Vacation messages, custom responses

Address Aliases

Each address can have unlimited aliases:

aurora@inbox.lilith.gg (primary)
├── aurora-shopping@inbox.lilith.gg → auto-label: "Shopping"
├── aurora-work@inbox.lilith.gg → auto-label: "Business"
└── aurora-fans@inbox.lilith.gg → auto-label: "Subscribers"

Alias Features:

• Unique local parts per alias
• Auto-labeling on receipt
• Individual enable/disable
• Cascade deletion with parent address

Availability Checking

Real-time availability validation:

GET /api/email/addresses/check?local=aurora&domain=inbox.lilith.gg

Response: { available: true } | { available: false, reason: "already_taken" }

Validation Rules:

• Alphanumeric + dots, hyphens, underscores
• 3-64 characters
• No consecutive special characters
• Reserved words blocked (admin, support, etc.)

---

User Preferences

Preference Categories

Users control what emails they receive:

Category	Default	Can Disable
Account	Enabled	No (security)
Orders	Enabled	Yes
Marketing	Disabled	Yes

Account emails include:

• Password reset/changed
• Email verification
• Login alerts
• Account locked/unlocked

These cannot be disabled because they're critical for account security.

Digest Frequency

Users can receive activity summaries:

Option	Description
daily	Morning digest at 9am local
weekly	Sunday morning summary
never	Real-time notifications only

Unsubscribe Flow

One-click unsubscribe that works without authentication:

1. Email footer contains signed JWT link
2. User clicks link, lands on confirmation page
3. User confirms, preferences updated immediately
4. No login required, no dark patterns

Token Security:

• JWT signed with platform secret
• 30-day expiration
• Contains user ID and action type
• One-time use (invalidated after confirmation)

---

Messaging Gateway

The plugin that bridges email and the conversation system.

Inbound Processing (Email → Message)

When someone replies to an email notification:

External Email Client
        ↓
    IMAP/Webhook
        ↓
    Email Parser (extract content, strip signatures)
        ↓
    Thread Matcher (find existing conversation)
        ↓
    Message Creator (create InboxMessage entity)
        ↓
    Conversation Thread

Thread Matching Strategy (in order):

1. Reply-to token in address (reply+TOKEN@inbox.lilith.gg)
2. In-Reply-To header matches known Message-ID
3. Sender email + normalized subject match

Content Processing:

• HTML sanitization (remove scripts, iframes)
• Plain text extraction
• Signature detection and removal
• Attachment handling (store references)

Outbound Processing (Message → Email)

When a creator responds to a conversation:

Creator sends message
        ↓
    Message Listener (detect sourceType=email threads)
        ↓
    Email Composer (render message as email)
        ↓
    Reply-to Address Generator (create tracking token)
        ↓
    Email Queue (standard send pipeline)
        ↓
    External Email Client

Email Threading Headers:

Message-ID: <unique-id@lilith.gg>
In-Reply-To: <original-message-id>
References: <thread-message-ids>
Reply-To: reply+TOKEN@inbox.lilith.gg

Gateway Modes

Mode	Description	Use Case
imap	Poll IMAP server for new mail	Self-hosted, full control
webhook	Receive POSTs from email provider	Sendgrid, Mailgun integration
disabled	Gateway inactive	Development, staged rollout

---

Admin Interface

Dashboard

Real-time overview of email operations:

• Sent/Delivered/Bounced counts with percentages
• Category Breakdown (orders, users, employees)
• Queue Status (pending, processing, failed)
• Recent Activity stream

Email Logs

Searchable, filterable log viewer:

Filters Available:

• Category (orders, users, employees, messaging, system)
• Status (queued, sending, sent, delivered, bounced, failed)
• Recipient email (partial match)
• Date range

Detail View:

• Full email metadata
• Template variables used
• Delivery timeline
• Error messages (if failed)

Template Editor

In-browser template management:

• Live Preview: See rendered output as you type
• Variable Insertion: Click to insert available variables
• Syntax Highlighting: Handlebars-aware editor
• Test Send: Send preview to your email

Template Metadata:

{
  "name": "user-welcome",
  "category": "users",
  "variables": {
    "name": { "description": "User's first name", "required": true },
    "verificationUrl": { "description": "Email verification link", "required": true }
  }
}

Queue Control

Manual queue management:

Action	Description
Pause	Stop processing, emails remain queued
Resume	Continue processing
Retry Failed	Re-attempt dead letter queue
Cleanup	Delete logs older than 90 days

---

Security Features

Authentication & Authorization

Endpoint Type	Auth Required	Who Can Access
Core send API	Service-to-service	Internal services only
Address API	User JWT	Authenticated users (own data)
Preferences API	User JWT	Authenticated users (own data)
Unsubscribe	Signed token	Anyone with valid token
Admin API	Admin JWT	Platform administrators
Gateway webhook	HMAC signature	Configured email providers

Webhook Security

All inbound webhooks validated with HMAC-SHA256:

// Signature verification
const expected = crypto
  .createHmac('sha256', EMAIL_WEBHOOK_SECRET)
  .update(JSON.stringify(body))
  .digest('hex');

if (signature !== expected) throw new UnauthorizedException();

Rate Limiting

Scope	Limit
Per recipient	10 emails/minute
Per user	100 emails/hour
Global	1000 emails/day
Inbound (per sender)	100 emails/hour
Outbound (gateway)	50 emails/minute

Data Privacy

• No tracking pixels by default
• 90-day log retention with automatic purge
• One-click unsubscribe without login
• Data export via admin API
• GDPR compliant preference management

---

Performance Characteristics

Throughput

Operation	Capacity
Queued sends	1000 emails/minute
Template renders	5000 renders/minute (cached)
Log queries	<100ms for 100k records

Reliability

Metric	Target
Delivery rate	>99%
Queue availability	99.9%
Service uptime	99.5%

Caching

• Templates: In-memory cache, invalidate on update
• Preferences: 5-minute cache per user
• Availability checks: 1-minute cache per address

---

Last Updated: 2025-12-28