# mailkit — agent briefing (load this first)

Public site: https://mailkit.getman.ai
Load this file from https://mailkit.getman.ai/llms.txt
Then https://mailkit.getman.ai/catalog.json and https://mailkit.getman.ai/commands.json

Product: mailkit 0.4.0. Local CLI for mail after install. macOS. Credentials in the login Keychain.

This folder is the **user guide**. It is not a map of the source tree.

Machine index:
- catalog.json — pages, ids, summaries
- commands.json — every verb, flags, which providers, whether --yes is required

## The one hard rule

Reading, drafting, and organizing are free and reversible.
**Sending is outward-facing.** `mailkit send` refuses without `--yes`.
You MUST also get an explicit human yes for **this** message (show To / Subject / Body) before you pass `--yes`.
Never send from a cron or any unattended loop.

Never put API tokens, Bridge passwords, or OAuth client JSON on argv or in shell history. Those prompts use hidden stdin.

## Providers

| Provider | Auth | Read | Draft/send | Organize | Labels/filters/thread |
|----------|------|------|------------|----------|------------------------|
| gmail | `auth add you@gmail.com` | yes | yes | yes | yes |
| fastmail | `auth add --provider fastmail you@fastmail.com` | yes | no | no | no |
| protonmail | `auth add --provider protonmail you@proton.me` | yes | yes | archive, mark-read/unread, trash | no |

Proton Mail needs a paid plan and Proton Mail Bridge running on this Mac.
Proton message ids look like `INBOX:12`, not Gmail hex ids.

## Parse output

Always pass `--json` when you will parse.
On failure: stderr starts with `error: ` and exit code is 1.

## First five commands

```
mailkit --version
mailkit auth list
mailkit auth doctor --json
mailkit read --json --max 5
mailkit show <id> --json
```

If `auth list` is empty, go to setup.md.

## Page order

start-here.md → setup.md → accounts.md → providers.md → read.md → write.md → organize.md → filters.md → json.md → agents.md → troubleshooting.md → reference.md