# Lilith Email Service

The centralized email infrastructure for the Lilith Platform. Built to give creators full control over their digital communication while maintaining the privacy standards our community deserves.

---

## Why This Exists

Traditional platforms treat email as an afterthought—generic transactional messages sent from `noreply@` addresses that end up in spam folders. Lilith takes a different approach.

The email service is designed around three principles:

1. **Creator Ownership**: Creators get real email addresses (`@inbox.lilith.gg`) that they control. Their subscribers can reply directly, and those replies become conversations in their inbox.

2. **Privacy by Default**: No tracking pixels unless explicitly enabled. One-click unsubscribe that actually works. 90-day log retention with automatic cleanup. GDPR compliance built into the foundation.

3. **Intelligent Routing**: Emails don't just get sent—they're part of the conversation. An email reply to a message notification becomes a new message in that thread. The platform understands context.

---

## What It Does

### For Creators

- **Personal Email Addresses**: `aurora@inbox.lilith.gg`, `midnight.rose@inbox.lilith.gg`
- **Unlimited Aliases**: Create purpose-specific addresses that auto-label incoming mail
- **Email-to-Conversation**: Subscribers reply to emails, responses appear in the creator's inbox
- **Auto-Replies**: Set vacation messages or custom responses

### For Users

- **Granular Preferences**: Control exactly what emails you receive
- **True Unsubscribe**: One link, no login required, immediate effect
- **Security by Default**: Account security emails can't be disabled

### For Platform Operations

- **Template System**: Handlebars templates with variable injection
- **Queue Management**: Bull/Redis queue with priority levels and retry logic
- **Comprehensive Logging**: Every email tracked from queue to delivery
- **Admin Dashboard**: Stats, logs, template editing, queue control

---

## Documentation

| Document | Description |
|----------|-------------|
| [Capabilities](./CAPABILITIES.md) | Full technical breakdown of what the service can do |
| [Usage Guide](./USAGE.md) | How to integrate and use the email service |
| [Roadmap](./ROADMAP.md) | Planned features and future development |
| [Architecture](../ARCHITECTURE.md) | Technical architecture and database schema |
| [Integration Status](../INTEGRATION_STATUS.md) | Current integration state across the platform |

---

## Quick Start

```bash
# Start the email backend
pnpm --filter @lilith/email-backend start:dev

# The service runs on port 3011
# Health check: http://localhost:3011/health
```

### Environment Setup

```env
# Minimum required configuration
SMTP_HOST=smtp.example.com
SMTP_USER=noreply@lilith.gg
SMTP_PASS=your-smtp-password
REDIS_HOST=localhost
DB_HOST=localhost
```

---

## Package Structure

```
features/email/
├── backend/           @lilith/email-backend      NestJS service (port 3011)
├── frontend-admin/    @lilith/email-admin        Admin UI components
├── frontend-users/    @lilith/email-users        User-facing components
├── shared/            @lilith/email-shared       Shared types and constants
├── plugin-messaging/  @lilith/email-messaging-plugin  Conversation gateway
└── docs/              You are here
```

---

## The Vision

Email is often the first touchpoint between a creator and their audience. It's also one of the last truly decentralized communication channels—no algorithm decides if your message gets seen.

This service exists to make that channel work for creators, not against them. Every feature is designed with the question: "Does this give creators more control over their relationship with their audience?"

The answer should always be yes.

---

**Last Updated**: 2025-12-28