Mailpilot

AI-powered email processing daemon that uses LLM classification to automatically organize, flag, and manage your inbox.

Features

• Smart LLM Classification - Uses any OpenAI-compatible API (OpenAI, Anthropic, Ollama, Azure, etc.) with confidence scoring, multi-action support, and vision capabilities for image analysis
• Powerful Email Actions - Move to folders, mark as spam, flag, mark read, delete — multiple actions per email with automatic folder creation
• Multi-Account Management - Process unlimited email accounts with per-account LLM providers, models, and classification rules
• Real-Time Dashboard - Modern web interface with live updates, activity logs, and provider health monitoring
• Rule Testing Sandbox - Test your classification prompts against sample emails before deploying to production
• Attachment Intelligence - Extract and analyze text from PDFs, Word docs, and spreadsheets via Apache Tika
• Dead Letter Queue - Failed classifications automatically queued for manual review with one-click retry
• Privacy-First Design - Email content never stored or logged; only message IDs and action records persisted
• Works With Any IMAP Server - Gmail, Outlook, FastMail, self-hosted — any provider with IMAP support, including servers with self-signed certificates
• Antivirus Integration - Optional ClamAV scanning to quarantine or flag suspicious attachments

Quick Start

New to Mailpilot? Try the Interactive Setup Wizard to generate a customized configuration for your email provider, LLM, and use case.

# Clone and install
git clone https://github.com/metal0/mailpilot.git
cd mailpilot
pnpm install

# Configure
cp config.example.yaml config.yaml
# Edit config.yaml with your settings

# Build and run
pnpm build
pnpm start

Minimal Configuration

llm_providers:
  - name: openai
    api_url: https://api.openai.com/v1/chat/completions
    api_key: ${OPENAI_API_KEY}
    default_model: gpt-4o-mini

accounts:
  - name: personal
    imap:
      host: imap.gmail.com
      username: ${GMAIL_USER}
      password: ${GMAIL_APP_PASSWORD}
      # For self-signed certificates, add trusted fingerprints:
      # trusted_tls_fingerprints:
      #   - "AA:BB:CC:DD:..." # SHA-256 fingerprint

Set environment variables:

export OPENAI_API_KEY="sk-..."
export GMAIL_USER="you@gmail.com"
export GMAIL_APP_PASSWORD="xxxx xxxx xxxx xxxx"

Documentation

Full documentation is available at metal0.github.io/mailpilot

Quick Links

Guide	Description
Setup Wizard	Interactive configuration generator
Installation	Setup and requirements
Quick Start	Get running in 5 minutes
Configuration Reference	All configuration options
Email Providers	Gmail, Outlook, Yahoo, iCloud, ProtonMail
LLM Providers	OpenAI, Anthropic, Ollama, OpenRouter
Prompts Guide	Writing classification prompts
API Reference	REST API documentation
Troubleshooting	Common issues and solutions

Docker Deployment

Basic

services:
  mailpilot:
    image: ghcr.io/metal0/mailpilot:latest
    ports:
      - "8080:8080"
    volumes:
      - ./config.yaml:/app/config.yaml:ro
      - ./data:/app/data
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}

Full (with Tika + ClamAV)

docker compose -f docker-compose.full.yaml up -d

Includes Apache Tika for attachment extraction and ClamAV for virus scanning.

Development

pnpm dev          # Run with hot reload
pnpm test         # Run tests
pnpm lint         # Run ESLint
pnpm typecheck    # Type check

Community

• Documentation - Full documentation site
• Matrix Chat - Join the community chat room
• GitHub Issues - Report bugs or request features
• GitHub Discussions - Feature requests and Q&A

License

AGPL-3.0