# Postlight User Guide

**"Chat with your mailbox — private, local-first."**

Welcome to Postlight, a privacy-focused email client with local AI capabilities. This guide will help you get started and make the most of Postlight's features.

## Table of Contents

1. [Installation](#installation)
2. [Getting Started](#getting-started)
3. [Adding Email Accounts](#adding-email-accounts)
4. [Core Features](#core-features)
5. [AI Features](#ai-features)
6. [Configuration](#configuration)
7. [Indexing & Battery Awareness](#indexing--battery-awareness)
8. [Troubleshooting](#troubleshooting)

## Installation

### Option 1: Flatpak (Recommended for Linux)

```bash
# Install from local bundle (when available)
flatpak install postlight.flatpak

# Or build from source (see packaging/README.md)
flatpak-builder --user --install --force-clean build-dir com.postlight.Postlight.yml

# Run Postlight
flatpak run com.postlight.Postlight
```

### Option 2: Nix/NixOS

```bash
# Build with Nix
nix build

# Run
./result/bin/postlight-ui
```

### Option 3: Build from Source

**Prerequisites:**
- Rust (latest stable)
- Node.js & pnpm
- Ollama (optional, for local AI features)

```bash
# Clone the repository
git clone https://github.com/postlight/postlight.git
cd postlight

# Install dependencies
cd postlight-ui
pnpm install

# Build and run
pnpm tauri build

# Or run in development mode
pnpm tauri dev
```

## Getting Started

### First Launch

1. **Launch Postlight** using your preferred installation method
2. **Add an email account** (see next section)
3. **Wait for initial sync** - Postlight will download your emails
4. **Optional: Set up local AI** - Install Ollama for AI features (see AI Features section)

### Installing Ollama (Optional)

For AI features like chat and semantic search, install Ollama:

```bash
# Linux/macOS
curl -fsSL https://ollama.com/install.sh | sh

# Pull recommended models
ollama pull llama3.1:8b-instruct  # For chat and summaries
ollama pull nomic-embed-text      # For semantic search
```

## Adding Email Accounts

### Supported Providers

Postlight works with any IMAP/SMTP email provider:
- Gmail
- Outlook/Office 365
- ProtonMail Bridge
- FastMail
- Self-hosted mail servers
- Any IMAP-compatible provider

### Account Setup

1. Click **"Add Account"** in the sidebar
2. Enter your email credentials:
   - **Email Address**: your@email.com
   - **IMAP Server**: imap.example.com
   - **IMAP Port**: 993 (usually)
   - **SMTP Server**: smtp.example.com
   - **SMTP Port**: 465 or 587
   - **Username**: Usually your email address
   - **Password**: Your email password or app-specific password

3. Click **"Connect"** and wait for initial sync

### Gmail Setup

For Gmail, you need an **app-specific password**:

1. Go to [Google Account Security](https://myaccount.google.com/security)
2. Enable 2-Step Verification if not already enabled
3. Go to "App passwords"
4. Generate a new app password for "Mail"
5. Use this password in Postlight

**Gmail Settings:**
- IMAP Server: `imap.gmail.com`
- IMAP Port: `993`
- SMTP Server: `smtp.gmail.com`
- SMTP Port: `465`

### Outlook/Office 365 Setup

**Outlook Settings:**
- IMAP Server: `outlook.office365.com`
- IMAP Port: `993`
- SMTP Server: `smtp.office365.com`
- SMTP Port: `587`

## Core Features

### Labels

Postlight uses Gmail-style labels to organize emails:

- **Apply Labels**: Select emails → right-click → "Apply Labels"
- **Create Labels**: Click "+" next to Labels section in sidebar
- **Filter by Label**: Click any label in the sidebar to view matching emails
- **Multiple Labels**: Emails can have multiple labels

### Threading

Emails are automatically grouped into conversation threads:

- Click a thread to expand and view all messages
- Replies are grouped with original messages
- Based on Message-ID and References headers

### Search

Postlight offers powerful search capabilities:

**Basic Search:**
- Type your query in the search box
- Searches subject, body, and participants

**Advanced Search Syntax:**
```
from:alice@example.com       # From specific sender
to:bob@example.com           # To specific recipient
tag:work                     # With specific label
has:attachment               # Has attachments
after:2024-01-01             # After date
before:2024-12-31            # Before date
```

**Hybrid Search** (when AI is enabled):
- Combines full-text search with semantic similarity
- Finds messages by meaning, not just keywords
- Example: "budget meeting" finds "financial planning discussion"

### Compose & Reply

- **New Email**: Click "Compose" button
- **Reply**: Click reply button on any message
- **Reply All**: Hold Shift while clicking reply
- **Forward**: Click forward button
- **Attachments**: Drag & drop files or click attach button

### Archive & Delete

- **Archive**: Removes from Inbox but keeps in All Mail
- **Delete**: Permanently deletes (moves to Trash)
- **Bulk Actions**: Select multiple emails with checkboxes

## AI Features

Postlight's AI features run locally by default for privacy. All AI features require Ollama to be installed and running.

### Automatic Summaries

When indexing is enabled, Postlight automatically:

- **Generates message summaries**: One-line summaries of each email
- **Creates thread briefs**: 3-bullet summaries of entire conversations
- **Extracts todos**: Identifies action items mentioned in emails
- **Suggests tags**: Recommends relevant labels based on content
- **Identifies entities**: Extracts people, projects, and concepts

### Semantic Search

Search by meaning, not just keywords:

- Enable hybrid search in Settings
- Example queries:
  - "meeting about Q4 budget" → finds financial planning emails
  - "vacation policy" → finds HR-related discussions
  - "deployment issues" → finds technical incidents

### Chat with Your Mailbox

Ask questions about your emails in natural language:

1. Click **"Chat"** button in sidebar
2. Ask questions like:
   - "What did Alice say about the project deadline?"
   - "Find emails from Bob about invoices"
   - "Summarize my unread work emails"
   - "What meetings do I have scheduled?"

3. Postlight will:
   - Search your emails
   - Provide answers with citations
   - Link to relevant messages

**Available Commands in Chat:**
- Search messages with filters
- Get thread summaries
- Open specific messages
- Apply labels to emails
- Draft replies (coming soon)

### Knowledge Graph

Postlight builds a knowledge graph from your emails:

- **Entities**: People, organizations, projects mentioned in emails
- **Concepts**: Topics and themes across your mailbox
- **Relationships**: How entities and concepts connect
- **Explore**: Click "Knowledge" tab to browse

## Configuration

Configuration file: `~/.postlight/config.toml`

### Basic Configuration

```toml
[profile]
db_path = "/home/user/.postlight/profile.db"
encrypt = false  # Set to true for database encryption

[index]
batch_size = 64  # Number of messages to process per batch
pause_on_battery = true  # Auto-pause indexing on battery power

[models]
provider = "ollama"  # "ollama", "openai", or "custom"
chat_model = "llama3.1:8b-instruct"
embed_model = "nomic-embed-text"
```

### Using OpenAI or Remote LLMs

```toml
[models]
provider = "openai"

[providers.openai]
base_url = "https://api.openai.com/v1"
api_key_cmd = "secret-tool lookup postlight openai_key"  # Command to retrieve API key

# Or use environment variable
api_key_env = "OPENAI_API_KEY"
```

**Privacy Note**: When using remote LLMs, your email content is sent to the provider. Postlight can redact PII (emails, phone numbers, etc.) before sending - enable in Settings.

### Custom LLM Endpoints

```toml
[models]
provider = "custom"

[providers.custom]
base_url = "http://localhost:8000/v1"  # Your LLM endpoint
# No API key needed for local endpoints
```

### Database Encryption

To encrypt your email database:

```toml
[profile]
encrypt = true
encryption_key_cmd = "secret-tool lookup postlight db_key"
```

**First time setup:**
1. Generate a strong encryption key
2. Store it securely in your OS keyring
3. Enable encryption in config.toml
4. Restart Postlight

## Indexing & Battery Awareness

### What is Indexing?

Indexing is the background process where Postlight:
- Analyzes email content
- Generates summaries
- Creates embeddings for semantic search
- Extracts todos and tags
- Updates the knowledge graph

### Indexing Controls

**In the UI:**
- Look for the "Indexer" widget in the sidebar
- Shows: Pending, Processing, and Failed counts
- **Pause**: Click "⏸️ Pause" to stop indexing
- **Resume**: Click "▶️ Resume" to continue

**Status Indicators:**
- ✓ Up to date - All emails indexed
- Processing: X - Currently indexing X messages
- Pending: X - X messages waiting to be indexed
- ⚠️ Paused - Indexing is paused
- Failed: X - X messages failed (check logs)

### Battery-Aware Indexing

When `pause_on_battery = true` in config:

- **On AC Power**: Indexing runs automatically
- **On Battery**: Indexing pauses to save battery
- **Automatic**: No manual intervention needed
- **Override**: You can manually resume even on battery

**Laptop Users**: This feature helps preserve battery life while allowing full indexing when plugged in.

## Troubleshooting

### IMAP Connection Issues

**Problem**: Can't connect to email server

**Solutions:**
1. Verify IMAP/SMTP settings are correct
2. Check firewall allows connections
3. For Gmail: Use app-specific password, not main password
4. For corporate email: Check if 2FA or VPN is required
5. Try toggling SSL/TLS settings

### Indexing Not Working

**Problem**: Messages not being summarized

**Solutions:**
1. Check Ollama is running: `ollama list`
2. Pull required models: `ollama pull llama3.1:8b-instruct`
3. Check indexer status in UI (should not show "Paused")
4. Check logs for errors: `~/.postlight/logs/`
5. Try manual trigger: Settings → "Trigger Indexing"

### Search Not Finding Messages

**Problem**: Search returns no results

**Solutions:**
1. Wait for initial indexing to complete
2. Check if messages are in the correct folder
3. Try simpler search terms
4. Check spelling and filters (from:, tag:, etc.)
5. For semantic search: Ensure embeddings are generated

### High CPU/Memory Usage

**Problem**: Postlight using too many resources

**Solutions:**
1. Reduce `batch_size` in config.toml (try 32 or 16)
2. Enable `pause_on_battery` to limit background work
3. Use smaller LLM models (e.g., `llama3.1:7b` instead of 70b)
4. Pause indexing when doing other intensive work
5. Check for runaway background processes

### Chat Not Responding

**Problem**: Chat feature doesn't work

**Solutions:**
1. Verify Ollama is running and models are loaded
2. Check chat model is configured correctly in config.toml
3. Test Ollama directly: `ollama run llama3.1:8b-instruct`
4. Check logs for LLM errors
5. Try a different model if current one is failing

### Database Corruption

**Problem**: Database errors or crashes

**Solutions:**
1. **Backup first**: Copy `~/.postlight/profile.db`
2. Run integrity check: `sqlite3 profile.db "PRAGMA integrity_check"`
3. If encrypted, ensure encryption key is correct
4. Try recovering from backup
5. Last resort: Re-sync from IMAP (delete DB and restart)

### Performance Issues with Large Mailboxes

**Problem**: Slow with many messages (100k+)

**Solutions:**
1. Wait for initial indexing to complete (can take hours)
2. Use filters to narrow views (labels, date ranges)
3. Archive old messages to reduce active set
4. Increase `batch_size` if you have good hardware
5. Consider using faster storage (SSD)

## Getting Help

- **Issues**: Report bugs at https://github.com/postlight/postlight/issues
- **Logs**: Check `~/.postlight/logs/` for error messages
- **Config**: Review `~/.postlight/config.toml` for settings
- **Community**: Join discussions on GitHub

## Privacy & Security Tips

1. **Use Local LLM**: Ollama keeps all data on your device
2. **Enable Encryption**: Encrypt database if device is shared
3. **Secure Credentials**: Store passwords in OS keyring
4. **Review Permissions**: Flatpak limits filesystem access
5. **Regular Backups**: Backup `~/.postlight/` directory
6. **PII Redaction**: Enable when using remote LLMs
7. **Check Logs**: Logs may contain email snippets - protect them

## Advanced Features

### Demo Data

For testing without real email:

```bash
# In the UI
Settings → "Initialize Demo Data"

# This creates sample emails and threads to explore features
```

### Multiple Profiles

Create separate profiles for different email personas:

```toml
# config-work.toml
[profile]
db_path = "/home/user/.postlight/work.db"

# config-personal.toml
[profile]
db_path = "/home/user/.postlight/personal.db"
```

Run with: `postlight-ui --config ~/.postlight/config-work.toml`

### Export Data

Export emails and metadata:

```bash
# SQLite database contains all data
sqlite3 ~/.postlight/profile.db

# Export to CSV, JSON, etc. using SQL queries
sqlite3 profile.db "SELECT * FROM messages" > messages.csv
```

## Keyboard Shortcuts

(Coming soon - shortcuts for common actions)

## Conclusion

Postlight combines the power of modern email clients with local AI capabilities, all while respecting your privacy. Explore the features, customize the configuration, and enjoy chatting with your mailbox!

For developers and contributors, see [README.md](README.md) for technical details and contribution guidelines.