122 lines
2.5 KiB
Markdown
122 lines
2.5 KiB
Markdown
# 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
|