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)

mailkit ships its own Google Desktop OAuth client. You do not open Google Cloud. 
mailkit auth add you@gmail.com
A browser opens. Click Allow. Pick your Google account and click Continue. mailkit’s Google client is verified and in production, so there is no warning screen. The first account becomes the default. Privacy: Privacy. 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.

​
Outlook (read + write)

Covers personal outlook.com / hotmail.com / live.com and Microsoft 365 work accounts. mailkit ships its own Microsoft Entra app id. You do not open the Azure portal.
  1. Run the consent:
mailkit auth add --provider outlook
  1. A browser opens. Pick the account. Click Accept.
  2. Check it:
mailkit auth doctor
mailkit read -a you@outlook.com --max 5
If you see Need admin approval, your organisation’s IT must allow mailkit. Send them this page. Personal accounts never see it. Scopes (delegated, least privilege):
ScopeAllowsDoes not allow
Mail.ReadWriteRead, drafts, read-state, move to Deleted Items or ArchivePermanent delete
Mail.SendSend—
User.ReadConfirm which mailbox you authorized—
offline_accessStay signed in between runs—
Microsoft issues a new refresh token on every refresh, and expires it after 90 days of inactivity. Daily use keeps it alive. A mailbox left alone for 90 days needs a new consent. Labels, filters, reconcile, file-inbox, untrash, and thread are not available on Outlook. They exit 1 with a clear error. Advanced: mailkit auth set-outlook-app <client_id> points mailkit at your own Entra app registration. Use it only when a build ships without an app id, or when your tenant requires its own app.

​
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.