Mail Agent

IMAP-based email triage with multi-tier escalation.

Overview

Mail Agent monitors IMAP accounts for new mail and automatically triages messages:

• L1 (Cheap Model): Fast classification using Fireworks llama-v3p1-8b

  • Spam → delete
  • Newsletter/receipt → archive
  • Shipping → dashboard + archive
  • Uncertain → escalate to L2

• L2 (James/Opus): Review via Clawdbot Gateway

  • Full context review
  • Can draft replies or escalate

• L3 (Johan): Signal notification

  • Important stuff only
  • Human decision required

Quick Start

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Set environment variables
export FIREWORKS_API_KEY=your-api-key
export PROTON_BRIDGE_PASSWORD=BlcMCKtNDfqv0cq1LmGR9g

# Run
python -m src.main

Configuration

Edit config.yaml:

server:
  host: 127.0.0.1
  port: 8025

accounts:
  proton:
    host: 127.0.0.1
    port: 1143
    username: tj@jongsma.me
    password: ${PROTON_BRIDGE_PASSWORD}
    tls: starttls
    folders:
      watch: [INBOX]
      archive: Archive

triage:
  enabled: true
  l1:
    provider: fireworks
    model: accounts/fireworks/models/llama-v3p1-8b-instruct
    api_key: ${FIREWORKS_API_KEY}

API Endpoints

Accounts

• GET /accounts - List all configured accounts
• GET /accounts/{id} - Get account details
• GET /accounts/{id}/mailboxes - List folders

Messages

• GET /accounts/{id}/messages?folder=INBOX&unread=true - List messages
• GET /accounts/{id}/messages/{uid}?folder=INBOX - Get full message
• PATCH /accounts/{id}/messages/{uid} - Update flags/move
• DELETE /accounts/{id}/messages/{uid} - Delete message

Events (SSE)

• GET /accounts/{id}/events?folder=INBOX - Subscribe to new mail events

Systemd Service

# Copy service file
cp systemd/mail-agent.service ~/.config/systemd/user/

# Edit to add FIREWORKS_API_KEY
systemctl --user edit mail-agent.service

# Enable and start
systemctl --user enable mail-agent
systemctl --user start mail-agent

# Check status
systemctl --user status mail-agent
journalctl --user -u mail-agent -f

Architecture

New Mail (IMAP IDLE)
    │
    ▼
┌─────────────────────┐
│  L1: Cheap Model    │  ~$0.20/1M tokens
│  Fast classification│
└─────────────────────┘
    │
    ▼ (uncertain/important)
┌─────────────────────┐
│  L2: James (Opus)   │  via Gateway
│  Context review     │
└─────────────────────┘
    │
    ▼ (needs human)
┌─────────────────────┐
│  L3: Johan          │  Signal notification
└─────────────────────┘

Shipping Dashboard

Shipping notifications are automatically posted to the James Dashboard:

POST http://100.123.216.65:9200/api/news
{
  "title": "📦 E3-1275 Server",
  "body": "Picked up by UPS. Expected Feb 3rd.",
  "type": "info",
  "source": "shipping"
}

Development

# Run with auto-reload
uvicorn src.main:app --reload --host 127.0.0.1 --port 8025

# Test IMAP connection
python -c "from src.imap import ImapClient; from src.config import get_config; c=get_config(); client=ImapClient('proton', c.accounts['proton']); client.connect(); print(client.list_mailboxes())"

License

Proprietary - Johan Jongsma