Skip to content
Primail

Why Primail is built for AI agents

Primail keeps IMAP/SMTP mail in one Rust core and exposes the same operations to you and to an agent you configure.

The consumer app does not bundle a chat model. MCP and CLI can read, search, draft, and send through Core. The external agent client may then send those results to a model provider you chose. That is separate from Primail’s optional Gemini helpers (see below).

There is no Settings AI Agents panel, no MCP auth token, and no local mail REST listener.

What you can do today

Section titled “What you can do today”

Build primail-mcp from this repository and point an MCP client at that stdio binary (see Install the MCP server). An agent can then:

  • Search and read. email_search, mailbox_list, email_get, thread_get, attachment download.
  • Draft and send. draft_create / draft_update / draft_send, or email_send. Drafts are local cache rows. They do not roam to other devices.
  • Triage. Archive, trash, spam, pin, snooze, move, flag, mute, mark read. There is no MCP set_aside tool.
  • Manage accounts. account_add, account_settings_update, account_password_update, account_remove.

The primail CLI is the other headless peer (primail --help lists the groups). Do not run primail-mcp --help; that binary does not parse it and starts the stdio server.

Why MCP

Section titled “Why MCP”

MCP is a stdio contract. Any client that can spawn a command with empty args can attach. Primail does not require a Primail-specific primail_* tool prefix. Tool names are account_list, mailbox_list, email_get, and so on.

Safety rails that actually exist

Section titled “Safety rails that actually exist”
  • Roles. receive_only blocks send (send_blocked_receive_only). managed is stored; it does not add a confirmation queue today. See Account roles.
  • Control scopes. ui_only / mcp_only restrict send, not listing or reading.
  • No token scopes. The process uses the same local profile as the app and CLI. There is no read / draft / send token.
  • No Primail send/read rate cap. Provider IMAP/SMTP throttles still apply.
  • Activity log. GUI, CLI, and MCP write the daily rotating file under the shared data directory (~/Library/Application Support/Primail/primail.log.YYYY-MM-DD on macOS). Settings → Support → Activity Log tails that file. There is no Settings → AI Agents → Audit log.

See Control scopes & safety rails.

Optional Gemini helpers

Section titled “Optional Gemini helpers”

MCP tools ai_classify_message, ai_summarize_message, and ai_smart_replies (and primail ai …) call Gemini when GEMINI_API_KEY is set in the environment or macOS Keychain. The GUI has no bundled summarize or smart-reply control. If the key is missing, those tools return ai_unavailable.

That Core call is a third destination, distinct from your mail provider and from whatever model your MCP client uses.

Start here

Section titled “Start here”

© 2026 Guangzhou StarStack Technology Co., Ltd.