# 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

```bash
# 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`:

```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:

```json
{
  "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

```bash
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