# gmail — Manual

## Overview
IMAP/SMTP access to Gmail. Requires `GMAIL_ADDRESS` and `GMAIL_APP_PASSWORD` in `.env`.
All list actions return messages **newest first**. Message IDs are **IMAP UIDs** — integers shown in list output.

## Actions

### send
Send a new email. `body` is **HTML** (wrap plain text in `<p>` if needed).
```
action=send  to="addr"  subject="..."  body="<p>Hello</p>"
```

### list
Paginated inbox. `offset` skips N messages from the newest (default 0).
`query` uses IMAP search syntax — see below.
```
action=list  max_results=10  offset=0  query='FROM "boss@company.com"'
```
Output per line: `● 4521 | From | Subject | Date`  (● = unread, ○ = read)
If more messages exist, output ends with `[N–M of total — use offset=K]`.

### list_unread
All unread messages, no pagination (up to 100). Call this first to orient.
```
action=list_unread
```

### read
Fetch full message by UID. **Auto-marks as read.** HTML bodies are converted to readable text; truncated at 5 000 chars.
```
action=read  uid="4521"
```

### reply
Reply in the original thread. Only needs the UID and your HTML body — From, Subject, thread headers are set automatically.
```
action=reply  uid="4521"  body="<p>Got it, thanks.</p>"
```

## IMAP query syntax (for `list`)
Criteria are ANDed when combined with a space.

| Goal | query value |
|------|-------------|
| From a sender | `FROM "someone@example.com"` |
| Subject contains | `SUBJECT "invoice"` |
| Since a date | `SINCE "01-Jan-2025"` |
| Before a date | `BEFORE "01-Feb-2025"` |
| Unread only | `UNSEEN` |
| Combine | `FROM "boss@co.com" SUBJECT "urgent"` |

## Typical workflow
1. `list_unread` — see what's new
2. `read uid="..."` — read a specific message
3. `reply uid="..." body="..."` — respond in thread