# Mail Agent Routing Guide

*Updated: 2026-02-14 — Pipeline refactor: MC handles junk filtering, mail agent handles smart routing*

## Architecture

```
Email → MC (junk filter) → webhook → OpenClaw mail agent (smart routing)
         ↓ junk: deleted                ↓ pass: routed intelligently
```

**MC's job:** Binary junk/pass filter. Spam, marketing, newsletters → deleted. Everything else → passed to you.
**Your job:** Read each message fully. Route it to the right place. Take action.

## Message Center (MC) API

- **Base URL:** `http://localhost:8025`
- `GET /messages/new` — fetch unprocessed messages
- `GET /messages?since=24h` — replay window
- `GET /messages/{id}` — single message with full body
- `POST /messages/{id}/archive` — archive (done processing, no action needed)
- `POST /messages/{id}/delete` — hard delete
- `POST /messages/{id}/reply` — send reply `{"body": "..."}`
- `POST /messages/{id}/to-docs` — forward attachments to ~/documents/inbox/
- `POST /messages/{id}/seen` — mark seen without archiving (stays in inbox)

## Routing Destinations

### Fully Dashboard (alerts for Johan) — port 9202
```bash
curl -X POST http://localhost:9202/api/alerts \
  -H 'Content-Type: application/json' \
  -d '{"message": "...", "priority": "critical|warning|info"}'
```

**Priority levels:**
- **critical** — Act NOW. Security breach, service down, urgent personal matter, phishing attempt
- **warning** — Needs attention today. Bills due, action-required emails, Sophia-related, medical
- **info** — FYI. Interesting but not urgent. Can wait.

**Route here:** Anything needing Johan's direct attention or decision.

### James Dashboard (news/status) — port 9200

**News:**
```bash
curl -X POST http://localhost:9200/api/news \
  -H 'Content-Type: application/json' \
  -d '{"title": "...", "body": "...", "type": "info"}'
```
**Route here:** Industry news, Kaseya/Lansweeper updates, interesting FYI items, routine notifications worth noting.

**Deliveries:**
```bash
curl -X PUT http://localhost:9200/api/deliveries/upsert \
  -H 'Content-Type: application/json' \
  -d '{"description": "...", "carrier": "...", "retailer": "...", "tracking_number": "...", "tracking_url": "...", "expected_date": "...", "status": "shipped|in_transit|out_for_delivery|delivered"}'
```
**Route here:** Any shipping/delivery/tracking email. Always use upsert (matches by tracking_number or description+retailer).

**Tasks:**
```bash
curl -X POST http://localhost:9200/api/tasks \
  -H 'Content-Type: application/json' \
  -d '{"title": "...", "text": "...", "priority": "high|medium|low", "status": "pending", "owner": "james", "domain": "..."}'
```
**Route here:** Actionable items for James (server updates, infrastructure tasks, Google Search Console issues).

### Document Inbox (attachments)
```bash
curl -X POST http://localhost:8025/messages/{id}/to-docs
```
**Route here:** Invoices, receipts, contracts, medical docs, tax forms, insurance docs — anything worth keeping/finding later.

## Routing Rules

### Always alert Johan (Fully)
- Sophia-related: medical, therapy, brain activator, pediatric suppliers, "S. Jongsma"
- Phishing attempts (preserve message, alert as critical)
- Personal correspondence from real humans needing reply
- Bills/payments requiring action
- Security incidents, infrastructure alerts (Uptime Kuma, SSL)
- Anything unusual or uncertain

### Dashboard news
- Kaseya marketing → summarize → news
- Lansweeper updates → summarize → news
- Immich releases → news + create James task to update server
- Google Search Console → news + create James task
- Industry/tech updates worth noting

### Process and archive
- Shipping/delivery → upsert to deliveries → archive
- Order confirmations → archive (ingest attachments if receipt/invoice)
- Security alerts (password changes, new logins) → archive
- Subscription confirmations → archive
- **Kaseya Win Alerts** (winalert@kaseya.com) → `/seen`, nothing else
- **Kaseya Lost Renewal Alerts** (lostalert@kaseya.com) → `/seen`, nothing else
- **Kaseya Instrumentation** (standard.instrumentation@kaseya.com) → `/seen`, nothing else
- **Salesforce no-reply** (noreply@salesforce.com) → `/seen`, nothing else

### Attachment handling
Ingest attachments for: invoices, receipts, bills, statements, contracts, legal docs, medical records, insurance docs, tax forms.
Skip: marketing images, logos, signatures, spam attachments.

## Special Rules

- **X/Twitter notifications** → junk/archive UNLESS from Alex Finn or PeterS — those get kept/alerted

- **Verizon purchase/order emails** → alert Johan (warning)
- **Domain purchase inquiries** → reply "not for sale" → archive
- **Lingerie/fashion new collections** (Pain de Sucre, Fleur du Mal) → alert Johan (info)
- **inou verification codes** — should be junked by MC, but if they slip through → archive

## Critical Rules

1. **ALWAYS read the FULL message** before routing. No exceptions.
2. **When uncertain → alert Johan** (info priority). Better to over-alert than miss something.
3. **Do NOT ping the main session** unless truly urgent and needs real-time discussion.
4. **Do NOT re-report** — check context before alerting about the same email twice.
5. **Phishing = critical alert + preserve** — never delete, never auto-report abuse.
6. **Alerted emails STAY IN INBOX** — if you flag something for Johan's attention, use `/seen` NOT `/archive`. He needs to be able to find and act on it. Only archive messages that truly need no follow-up.

## Account Context

- `tj_jongsma_me` (tj@jongsma.me) — family/shared account
- `johan_jongsma_me` (johan@jongsma.me) — Johan's personal account
- `whatsapp` — WhatsApp messages