MCP tool reference

Tool names are the name = attributes on primail-mcp handlers (for example account_list, mailbox_list, email_get, email_search, email_send). The obsolete primail_list_messages family is not registered.

This page is a complete name index plus examples for common calls. It is not an exhaustive JSON Schema dump. The running server exposes schemas through the standard MCP tools/list method. Do not run primail-mcp --help to discover them.

There is no token Scope: column. Errors use Core codes such as validation_error, account_not_found, message_not_found, send_blocked_receive_only, send_blocked_scope, and ai_unavailable.

Ids are opaque strings. Do not parse them.

Name index

Accounts. account_add, account_add_oauth, account_add_batch, account_list, account_get, account_remove, account_remove_batch, account_group_set, account_settings_get, account_settings_update, account_password_update

Folders and mailbox list. folder_list, folder_create, folder_rename, folder_delete, mailbox_list

Read and search. email_get, email_search, email_search_status, email_search_repair, email_attachment_download, email_export, email_sent_copies, email_sent_copy_status, thread_get

Send, drafts, outbox. email_send, email_send_batch, email_send_multi_account, draft_create, draft_list, draft_update, draft_delete, draft_send, schedule_cancel, outbox_list, outbox_cancel, outbox_retry

Triage. email_archive, email_trash, email_spam, email_unspam, email_move, email_move_to_inbox, email_flag, email_pin, email_mute, email_snooze, email_unsnooze, email_remind, email_mark_read, email_mark_all_read, email_set_category, email_delete_permanently, email_empty_trash, email_unsubscribe, email_rsvp, email_spam_report

Senders and gatekeeper. sender_block, sender_unblock, email_blocked_senders, gatekeeper_accept, gatekeeper_block, gatekeeper_block_domain, gatekeeper_block_all, gatekeeper_mode_get, gatekeeper_mode_set

Threads. thread_detach, thread_merge, thread_get

Templates and smart folders. template_create, template_list, template_get, template_update, template_delete, template_send, smart_folder_create, smart_folder_list, smart_folder_update, smart_folder_delete

Identities and signatures. identity_list, identity_get, identity_create_alias, identity_update, identity_delete, identity_set_default, signature_list, signature_get, signature_create, signature_update, signature_delete, signature_set_default, signature_clear_default, sender_resolve

Contacts, IMAP sync, health. contacts_list, sync_run, sync_status, system_health, activity_log_read, entitlement_status

Optional Gemini helpers. ai_classify_message, ai_summarize_message, ai_smart_replies — require GEMINI_API_KEY; otherwise ai_unavailable. The GUI does not call these.

There is no set_aside tool.

Common examples

account_list

Optional filters: domain, group, role (personal / managed / receive_only).

{ "role": "personal" }

mailbox_list

account_id is required. Optional folder (provider path), limit, offset, only (pinned / flagged / snoozed / folderless), or role (inbox / sent / drafts / trash / junk / archive). Do not combine role with folder or only.

{ "account_id": "ACCOUNT_ID", "role": "inbox", "limit": 50 }

email_get

{ "account_id": "ACCOUNT_ID", "message_id": "MESSAGE_ID" }

Optional max_body_bytes, cursor.

email_search

query is required. Optional account_id, limit, folder, from, category, cursor.

{ "query": "invoice", "limit": 20 }

email_send

Required: account_id, to, subject, body. Optional cc, bcc, reply_to, reply_to_message_id, client_request_id, send_at (RFC 3339 UTC; schedules a local send on this device). No GUI Undo Send hold.

{
  "account_id": "ACCOUNT_ID",
  "to": ["[email protected]"],
  "subject": "Status",
  "body": "Shipped."
}

draft_create

Required: account_id. Optional to, subject, body, in_reply_to_message_id, forward_of_message_id. Saved in the local cache.

email_archive / email_trash / email_spam

{ "account_id": "ACCOUNT_ID", "message_ids": ["MESSAGE_ID"] }

Optional source_folder.

email_snooze

Uses until (RFC 3339 UTC), not wake_at.

{
  "account_id": "ACCOUNT_ID",
  "message_id": "MESSAGE_ID",
  "until": "2026-10-05T16:00:00Z"
}

account_remove

{ "account_id": "ACCOUNT_ID" }

No also_delete_on_cloud field. Same local cleanup as Remove an email account.

account_settings_update

Partial update. role and control_scope use the Core enums documented on Account roles.

Error shape

Typical failure envelope:

{
  "error": {
    "code": "send_blocked_receive_only",
    "message": "Send blocked: account role is receive_only",
    "suggestion": "This account is set to receive_only. Change the role via account_settings_update."
  }
}

Codes are snake_case Core codes, not ROLE_FORBIDDEN or RATE_LIMITED.