{
  "name": "mailkit",
  "version": "0.4.0",
  "updated": "2026-08-20",
  "global": {
    "account_flag": ["-a", "--account"],
    "json_flag": ["--json"],
    "error_shape": "error: <message> on stderr, exit 1",
    "send_rule": "mailkit send refuses without --yes. Agents must also get a human yes for this message."
  },
  "providers": {
    "gmail": {
      "auth": "mailkit auth add you@gmail.com",
      "credential": "Google OAuth refresh token in Keychain",
      "verbs": "all"
    },
    "fastmail": {
      "auth": "mailkit auth add --provider fastmail you@fastmail.com",
      "credential": "Fastmail API token (Mail, read-only) in Keychain",
      "verbs": ["auth", "read", "search", "show"]
    },
    "protonmail": {
      "auth": "mailkit auth add --provider protonmail you@proton.me",
      "credential": "Proton Mail Bridge mailbox password in Keychain (not the Proton login)",
      "requires": "Paid Proton plan. Bridge running on this Mac (IMAP 127.0.0.1:1143, SMTP 127.0.0.1:1025).",
      "verbs": ["auth", "read", "search", "show", "draft", "reply", "drafts", "send", "archive", "mark-read", "mark-unread", "trash"],
      "message_ids": "mailbox:uid (example INBOX:12)"
    }
  },
  "commands": [
    {
      "name": "auth set-client",
      "usage": "mailkit auth set-client <client.json>",
      "purpose": "Store the Google Desktop OAuth client JSON in Keychain. Once per machine.",
      "providers": ["gmail"],
      "yes_required": false,
      "json": false,
      "see": "setup.md"
    },
    {
      "name": "auth add",
      "usage": "mailkit auth add [--provider gmail|fastmail|protonmail] [--force] [EMAIL]",
      "purpose": "Authorize an account. Gmail: browser consent. Fastmail: API token on stdin. Proton Mail: Bridge mailbox password on stdin. Never pass secrets as argv.",
      "providers": ["gmail", "fastmail", "protonmail"],
      "yes_required": false,
      "json": false,
      "see": "setup.md"
    },
    {
      "name": "auth list",
      "usage": "mailkit auth list",
      "purpose": "List authorized accounts and providers. Default is marked (default).",
      "providers": ["gmail", "fastmail", "protonmail"],
      "yes_required": false,
      "json": false,
      "see": "accounts.md"
    },
    {
      "name": "auth default",
      "usage": "mailkit auth default EMAIL",
      "purpose": "Set the account used when --account is omitted.",
      "providers": ["gmail", "fastmail", "protonmail"],
      "yes_required": false,
      "json": false,
      "see": "accounts.md"
    },
    {
      "name": "auth remove",
      "usage": "mailkit auth remove EMAIL",
      "purpose": "Delete the local Keychain credential. Does not revoke at Google/Fastmail/Proton.",
      "providers": ["gmail", "fastmail", "protonmail"],
      "yes_required": false,
      "json": false,
      "see": "accounts.md"
    },
    {
      "name": "auth doctor",
      "usage": "mailkit auth doctor [-a EMAIL] [--json]",
      "purpose": "Check stored credentials. Gmail: refresh OAuth. Fastmail: JMAP session. Proton Mail: Bridge IMAP login. Exit non-zero if any fail.",
      "providers": ["gmail", "fastmail", "protonmail"],
      "yes_required": false,
      "json": true,
      "see": "accounts.md"
    },
    {
      "name": "read",
      "usage": "mailkit read [-a EMAIL] [-q QUERY] [--max N] [--unread] [--json]",
      "purpose": "List inbox (or query) message summaries. Default --max 20. Bare listing is the inbox.",
      "providers": ["gmail", "fastmail", "protonmail"],
      "yes_required": false,
      "json": true,
      "see": "read.md"
    },
    {
      "name": "search",
      "usage": "mailkit search QUERY [-a EMAIL] [--max N] [--json]",
      "purpose": "Search. Gmail: full Gmail syntax. Fastmail/Proton Mail: from:, from:(a OR b), -from:, in:inbox only.",
      "providers": ["gmail", "fastmail", "protonmail"],
      "yes_required": false,
      "json": true,
      "see": "read.md"
    },
    {
      "name": "show",
      "usage": "mailkit show MESSAGE_ID [-a EMAIL] [--json]",
      "purpose": "One full message (summary plus body and Message-ID header).",
      "providers": ["gmail", "fastmail", "protonmail"],
      "yes_required": false,
      "json": true,
      "see": "read.md"
    },
    {
      "name": "thread",
      "usage": "mailkit thread THREAD_ID [-a EMAIL] [--json]",
      "purpose": "One Gmail thread.",
      "providers": ["gmail"],
      "yes_required": false,
      "json": true,
      "see": "read.md"
    },
    {
      "name": "draft",
      "usage": "mailkit draft --to ADDR --subject S --body TEXT [--cc ADDR] [--thread ID] [--attach PATH]... [--json]",
      "purpose": "Create a draft. Never sends.",
      "providers": ["gmail", "protonmail"],
      "yes_required": false,
      "json": true,
      "see": "write.md"
    },
    {
      "name": "reply",
      "usage": "mailkit reply MESSAGE_ID --body TEXT [--reply-all] [--json]",
      "purpose": "Create a draft reply in-thread. Never sends.",
      "providers": ["gmail", "protonmail"],
      "yes_required": false,
      "json": true,
      "see": "write.md"
    },
    {
      "name": "drafts",
      "usage": "mailkit drafts [--json]",
      "purpose": "List drafts.",
      "providers": ["gmail", "protonmail"],
      "yes_required": false,
      "json": true,
      "see": "write.md"
    },
    {
      "name": "send",
      "usage": "mailkit send --yes (--draft ID | --to ADDR --subject S --body TEXT) [--cc ADDR] [--html-file PATH] [--attach PATH]...",
      "purpose": "Send a draft or a new message. Refuses without --yes. Do not combine --attach with --draft.",
      "providers": ["gmail", "protonmail"],
      "yes_required": true,
      "json": true,
      "see": "write.md"
    },
    {
      "name": "label",
      "usage": "mailkit label [IDS]... --add NAME [--remove NAME] [--create] [-q QUERY]",
      "purpose": "Add/remove Gmail labels by name.",
      "providers": ["gmail"],
      "yes_required": false,
      "json": true,
      "see": "organize.md"
    },
    {
      "name": "archive",
      "usage": "mailkit archive [IDS]... [-q QUERY]",
      "purpose": "Remove from inbox (Gmail: drop INBOX label. Proton Mail: move to Archive).",
      "providers": ["gmail", "protonmail"],
      "yes_required": false,
      "json": true,
      "see": "organize.md"
    },
    {
      "name": "mark-read",
      "usage": "mailkit mark-read [IDS]... [-q QUERY]",
      "purpose": "Mark read.",
      "providers": ["gmail", "protonmail"],
      "yes_required": false,
      "json": true,
      "see": "organize.md"
    },
    {
      "name": "mark-unread",
      "usage": "mailkit mark-unread [IDS]... [-q QUERY]",
      "purpose": "Mark unread.",
      "providers": ["gmail", "protonmail"],
      "yes_required": false,
      "json": true,
      "see": "organize.md"
    },
    {
      "name": "trash",
      "usage": "mailkit trash [IDS]... [-q QUERY]",
      "purpose": "Move to Trash. Recoverable. Not permanent delete.",
      "providers": ["gmail", "protonmail"],
      "yes_required": false,
      "json": true,
      "see": "organize.md"
    },
    {
      "name": "untrash",
      "usage": "mailkit untrash [IDS]... [-q QUERY]",
      "purpose": "Restore from Trash.",
      "providers": ["gmail"],
      "yes_required": false,
      "json": true,
      "see": "organize.md"
    },
    {
      "name": "labels",
      "usage": "mailkit labels [--json]",
      "purpose": "List Gmail labels.",
      "providers": ["gmail"],
      "yes_required": false,
      "json": true,
      "see": "organize.md"
    },
    {
      "name": "labels-create",
      "usage": "mailkit labels-create NAME",
      "purpose": "Create a Gmail user label.",
      "providers": ["gmail"],
      "yes_required": false,
      "json": true,
      "see": "organize.md"
    },
    {
      "name": "filter list",
      "usage": "mailkit filter list [--json]",
      "purpose": "List Gmail filters.",
      "providers": ["gmail"],
      "yes_required": false,
      "json": true,
      "see": "filters.md"
    },
    {
      "name": "filter create",
      "usage": "mailkit filter create --label NAME [--from ADDR] [--to ADDR] [--subject S] [-q QUERY] [--skip-inbox] [--mark-read] [--create-label]",
      "purpose": "Create a Gmail filter. Affects future mail only.",
      "providers": ["gmail"],
      "yes_required": false,
      "json": true,
      "see": "filters.md"
    },
    {
      "name": "filter delete",
      "usage": "mailkit filter delete ID",
      "purpose": "Delete a Gmail filter.",
      "providers": ["gmail"],
      "yes_required": false,
      "json": true,
      "see": "filters.md"
    },
    {
      "name": "reconcile",
      "usage": "mailkit reconcile [--json]",
      "purpose": "Apply existing Gmail filters to mail already in the inbox.",
      "providers": ["gmail"],
      "yes_required": false,
      "json": true,
      "see": "filters.md"
    },
    {
      "name": "file-inbox",
      "usage": "mailkit file-inbox [--older-than N] [--json]",
      "purpose": "Archive folder-labeled inbox mail older than N days (default 1). Keeps the label.",
      "providers": ["gmail"],
      "yes_required": false,
      "json": true,
      "see": "filters.md"
    },
    {
      "name": "init-skill",
      "usage": "mailkit init-skill [--target claude-code|opencode|path:DIR] [--json]",
      "purpose": "Install the bundled agent skill into a coding agent. Optional if the agent already has this user guide.",
      "providers": [],
      "yes_required": false,
      "json": true,
      "see": "agents.md"
    }
  ]
}