Quick Start Guide

Get Mailpilot processing your emails in just 5 minutes.

Prerequisites

Before starting, you'll need:

• ✅ Node.js 22+ installed
• ✅ An email account with IMAP access
• ✅ An LLM API key (OpenAI, Anthropic, or Ollama running locally)

Step 1: Install

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

Step 2: Create Configuration

Copy the example configuration:

cp config.example.yaml config.yaml

Edit config.yaml with this minimal setup:

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
      port: 993
      username: ${GMAIL_USER}
      password: ${GMAIL_APP_PASSWORD}

    folders:
      - name: INBOX
        llm_provider: openai
        prompt: |
          Classify this email into ONE of these categories:
          - important: Urgent emails requiring immediate attention
          - newsletters: Marketing and promotional emails
          - social: Social media notifications
          - receipts: Purchase confirmations and receipts
          - spam: Unwanted or suspicious emails

          Return your classification as JSON:
          {
            "action": "move",
            "folder": "category-name",
            "confidence": 0.95
          }

Step 3: Set Environment Variables

Create a .env file or export variables:

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

Step 4: Build and Run

pnpm build
pnpm start

You should see output like:

[INFO] Mailpilot starting...
[INFO] Dashboard available at http://localhost:8080
[INFO] Connecting to IMAP: imap.gmail.com
[INFO] Processing folder: INBOX (15 unread messages)

Step 5: Access the Dashboard

Open your browser to http://localhost:8080

The dashboard shows:

• Activity Feed: Recent email classifications
• Statistics: Processing metrics
• Health Status: IMAP and LLM provider status
• Testing Sandbox: Test your prompts safely

Step 6: Test Your Rules

Before processing real emails, test your classification prompt:

1. Go to Testing Sandbox in the dashboard
2. Paste a sample email
3. Click Test Classification
4. Review the LLM's response

Adjust your prompt until you get consistent, accurate classifications.

Example Classification Results

After running for a few minutes, you should see emails automatically:

• Moved to appropriate folders (important, newsletters, etc.)
• Flagged based on importance
• Marked as read if specified

What's Happening?

Mailpilot is:

1. Connecting to your IMAP server via TLS
2. Fetching unread emails from INBOX
3. Classifying each email using your LLM prompt
4. Applying actions (move, flag, read) based on the classification
5. Logging all activity to the dashboard

Common Issues

"Authentication failed"

• Gmail: Make sure you're using an app password, not your regular password
• Outlook: You need to enable IMAP access first

"LLM provider error"

• Verify your API key is correct
• Check your API usage limits
• Ensure api_url points to the correct endpoint

"No emails processed"

• Check that you have unread emails in INBOX
• Verify IMAP connection in dashboard health status
• Check logs for specific errors

Next Steps

Advanced Quickstart: Docker

For production deployment:

# docker-compose.yml
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}
      - GMAIL_USER=${GMAIL_USER}
      - GMAIL_APP_PASSWORD=${GMAIL_APP_PASSWORD}
    restart: unless-stopped

docker compose up -d

Getting Help

• Troubleshooting Guide - Common issues and solutions
• Matrix Chat - Community support
• GitHub Issues - Bug reports

Congratulations! 🎉 Your emails are now being intelligently processed by AI.