Point your agent at this folder (docs/use/). Load llms.txt, then catalog.json and commands.json. Open a markdown page only when you need the steps. mailkit init-skill installs a bundled skill into some coding agents. This user guide is the public, provider-current source. Prefer it when both exist.

​
Operating loop

  1. mailkit --version — this guide matches 0.4.0.
  2. mailkit auth list — note provider tags.
  3. If empty: setup.md. You will need a human for Google consent, a Fastmail token, or a Bridge password.
  4. mailkit auth doctor --json before a batch of reads if the account might be stale.
  5. Read with --json. Organize with ids from those results, or -q after you have shown the human the match.
  6. Draft freely. Send only after the send ritual below.

​
Send ritual (required)

Before every mailkit send:
  1. Show To, Cc, Subject, Body, attachment names.
  2. Get an unambiguous yes for this payload.
  3. Run mailkit send … --yes.
  4. Never add --yes because a draft exists.
Without --yes the CLI already refuses. That is not a substitute for the human yes.

​
Secrets

  • Do not echo Fastmail tokens or Bridge mailbox passwords.
  • Do not pass them as flags or positional args.
  • Do not write them into the repo, tickets, or chat logs.
  • OAuth client JSON goes through mailkit auth set-client <file> only.

​
Provider routing

Read commands.json → providers and each command’s providers list. Do not call Gmail-only verbs on Fastmail or Proton Mail. Do not call send on Fastmail.

​
Queries

On Fastmail and Proton Mail, only from:, from:(a OR b), -from:, in:inbox. If you need is:unread, use mailkit read --unread instead of stuffing that token into search.

​
Bulk organize

For -q that could match many messages: mailkit search first, report the count, confirm the scope, then run archive/trash/label.

​
Cron

Unattended jobs may read, doctor, organize, and draft. They must never call send.