Mail Agent

Simple IMAP/SMTP API with webhook notifications for OpenClaw.

Overview

Mail Agent is a thin layer over IMAP that:

1. Monitors mailboxes via IMAP IDLE (push notifications)
2. Provides a REST API for reading/moving/deleting messages
3. POSTs new mail to OpenClaw webhook for processing

All intelligence lives in OpenClaw. Mail Agent is just the pipe.

Quick Start

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

# Install dependencies
pip install -r requirements.txt

# 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

webhook:
  enabled: true
  url: http://localhost:18789/hooks/mail
  token: kuma-alert-token-2026

API Endpoints

Health

• GET /health - Health check

Accounts

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

Messages

• GET /accounts/{id}/messages?folder=INBOX&limit=20 - 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}?folder=INBOX - Delete message

Events (SSE)

• GET /events?accounts=proton - Subscribe to new mail events

Webhook Payload

When new mail arrives, POSTs to webhook:

{
  "account": "proton",
  "uid": 12345,
  "folder": "INBOX",
  "from": "sender@example.com",
  "to": ["recipient@example.com"],
  "subject": "Hello",
  "date": "2026-01-31T10:00:00Z",
  "preview": "First 1000 chars...",
  "body": "Full text up to 10KB",
  "has_attachments": false,
  "attachment_names": []
}

Systemd Service

systemctl --user restart mail-agent
systemctl --user status mail-agent
journalctl --user -u mail-agent -f

Architecture

New Mail (IMAP IDLE)
    │
    ▼
┌─────────────────────┐
│  POST to webhook    │
│  (raw email data)   │
└─────────────────────┘
    │
    ▼
┌─────────────────────┐
│  OpenClaw (James)   │  ← All decisions here
│  Archive/Delete/    │
│  Reply/Escalate     │
└─────────────────────┘

License

Proprietary - Johan Jongsma