Run these steps on the Mac that will call mailkit. Tokens live in that user’s login Keychain. They do not follow you to another machine. Never put tokens, Bridge passwords, or OAuth client JSON on the command line. ps and shell history would see them. mailkit prompts on stdin with echo off.

​
Gmail (full access)

You need a Google Desktop OAuth client that you own, with the Gmail API enabled, and the consent screen published to Production (Testing mode expires refresh tokens after 7 days).
  1. In Google Cloud: create (or reuse) a project. Enable Gmail API.
  2. Consent screen: External is fine. Publish to Production.
  3. Create an OAuth client of type Desktop app. Download the JSON.
  4. Store it once:
mailkit auth set-client /path/to/client_secret.json
  1. Authorize an account (opens a browser):
mailkit auth add you@gmail.com
Google may show “hasn’t verified this app.” That is expected for a personal client. Continue through Advanced. The first account becomes the default. Scopes mailkit requests (least privilege):
ScopeAllowsDoes not allow
gmail.modifyRead, labels, archive, trashPermanent delete
gmail.composeDrafts and send—
gmail.settings.basicFiltersOther account settings
If auth add saved a token but could not verify yet, wait 1–2 minutes and run mailkit read.

​
Fastmail (read-only)

  1. Fastmail: Settings → Privacy & Security → Manage API tokens → New API token.
  2. Scope Mail. Mark it read-only.
  3. Register:
mailkit auth add --provider fastmail you@fastmail.com
Paste the token at the hidden prompt. Draft, send, organize, labels, filters, and thread are not available on Fastmail. They exit 1 with a clear error.

​
Proton Mail (read + send, via Bridge)

Proton Mail has no public mail API. mailkit uses Proton Mail Bridge on this Mac. Needs: a paid Proton plan, Bridge installed, signed in, running.
  1. Install Bridge from proton.me/mail/bridge.
  2. Copy the mailbox password from Bridge. This is not your Proton login.
  3. Register:
mailkit auth add --provider protonmail you@proton.me
Paste the mailbox password at the hidden prompt. Bridge listens on loopback only: IMAP 127.0.0.1:1143, SMTP 127.0.0.1:1025. If Bridge is stopped, read and send fail. auth doctor will say Bridge is not reachable.

​
Check

mailkit auth list
mailkit auth doctor
mailkit read --max 5 --json
--force overwrites an address that already has a different provider’s credential. That destroys the old credential. Only use it when you mean to. Next: Accounts.