List all configured email accounts in Apple Mail.

Returns each account's id (UUID), display name, email addresses, account type, and enabled state. Account ids are stable across name changes; prefer them over names for identifying accounts.

Returns: Dictionary containing the accounts list.

Example: >>> list_accounts() {"success": True, "accounts": [ {"id": "B21B254B-...", "name": "Gmail", "email_addresses": ["me@gmail.com"], "account_type": "imap", "enabled": True}, ... ]}

List all Mail.app rules (read-only).

Returns each rule's display name and enabled state. Rule names are NOT guaranteed unique — Mail allows duplicates — and rules have no stable id via AppleScript. This tool is read-only; mutation (enable/disable, create, delete) is tracked as a separate enhancement.

Returns: Dictionary containing the rules list.

Example: >>> list_rules() {"success": True, "rules": [ {"name": "Junk filter", "enabled": True}, {"name": "News From Apple", "enabled": False}, ... ], "count": 2}

Delete a Mail.app rule by 1-based positional index.

Destructive — requires user confirmation via MCP elicitation before running. Cannot be undone (Mail.app does not version rule history).

Create a new Mail.app rule.

Additive — no confirmation prompt. Mail.app appends new rules to the end of the rule list, so the returned rule_index equals the new total rule count.

Update an existing Mail.app rule (patch semantics).

Patch semantics: only fields you provide are changed. conditions and actions, when provided, REPLACE their respective structures wholesale (not merged).

Conditional confirmation: prompts the user via MCP elicitation only when the patch touches conditions, actions, or match_logic — those replacements are irrecoverable. Patches limited to enabled and/or name (trivially reversible) skip the prompt. The enable/disable path replaces the removed set_rule_enabled tool: call update_rule(rule_index, enabled=True|False).

Refuses to update any rule whose existing actions include something outside the supported schema (run-AppleScript, redirect, reply text, play sound, custom highlight color); raises MailUnsupportedRuleActionError. Edit such rules in Mail.app's UI.

List all mailboxes for an account.

Search for messages matching criteria. Returns metadata-only rows.

Two corpus modes:

• source=None (default): search the given account/mailbox using the IMAP/AppleScript SEARCH path. account is required.

• source=[id1, id2, ...]: scope the search to the specific messages identified by the given ids. account/mailbox are ignored; the connector resolves each id self-sufficiently. The resulting message dicts are post-filtered by the other criteria (sender_contains, read_status, etc.) — full filter composition. The literal token "SELECTED" may appear in the list and is server-resolved at call time to Mail.app's current UI selection (zero-or-more messages). Mixed lists like ["SELECTED", "12345"] are valid. Missing ids drop out silently (partial-results).

For thread retrieval, call get_thread(message_id) to expand an anchor into thread member ids, then optionally pipe those ids into source=[ids] for filtered metadata browsing or into get_messages([ids]) for full bodies.

Get full details of one or more messages, with bodies.

Returns a list of message dicts (possibly of length 0 or 1). Pair with search_messages (metadata-only) and get_thread (thread member ids) to fetch bodies for specific messages.

Update one or more messages: change read state, flag, and/or move, in one atomic call (#135).

Patch semantics — caller specifies only the fields to change. All specified mutations apply in a single AppleScript pass via the bulk-update helper. Replaces the previous mark_as_read, move_messages, and flag_message tools.

Order of operations (matters for IMAP): read-state and flag changes apply first (in source mailbox), then the move. IMAP requires the message to exist in the source folder for STORE before MOVE.

Return all messages in the thread containing the given message.

Looks up the anchor message by its id, then reconstructs the conversation via the connector's tiered IMAP threading dispatch (Tier 1 X-GM-THRID for Gmail, Tier 3 header-search BFS fallback) or the AppleScript path. Result rows are sorted by date_received ascending.

The returned ids can be piped into search_messages(source=[ids]) for filtered metadata or get_messages([ids]) for full bodies.

Known limitation: thread members whose subject was rewritten mid-conversation are missed on the AppleScript fallback path (subject prefilter tradeoff).

Save attachments from a message to a directory.

Create a new mailbox/folder.

Rename and/or re-parent (move) an existing mailbox.

Two delivery paths:

• Rename only (new_name set, new_parent is None): AppleScript. Fast, no IMAP credentials needed.

• Move (new_parent set; optionally combined with rename): IMAP RENAME. Requires IMAP credentials in Keychain (#73 opt-in flow) — returns error_type: "imap_required" when missing.

At least one of new_name / new_parent must be provided.

Refused (#164): operations targeting the bare [Gmail] parent or any [Gmail]/... child path return error_type: "unsupported_gmail_system_label". Applies to both the source name and the resulting destination (new_parent join). Gmail's IMAP server doesn't support normal RENAME semantics for these paths; user-created Gmail labels (Newsletters, etc.) behave normally.

Delete a mailbox via IMAP.

Mail.app's AppleScript dictionary doesn't expose a working delete primitive for mailboxes, so this operation goes through IMAP. Requires IMAP credentials in Keychain (#73 opt-in flow) — returns error_type: "imap_required" when missing.

Always elicits user confirmation (destructive). By default refuses non-empty mailboxes to prevent accidental data loss; pass delete_messages=True to cascade.

Refused (#164): targeting the bare [Gmail] parent or any [Gmail]/... child path returns error_type: "unsupported_gmail_system_label". Gmail's IMAP server doesn't support DELETE for these paths.

Delete messages (always moves to the account's Trash mailbox).

List all stored email templates.

Templates live as files at ~/.apple_mail_mcp/templates/.md. Override the location with the APPLE_MAIL_MCP_HOME environment variable.

Returns: Dictionary with each template's name and subject (or null if no subject header is set).

Read a single template by name.

Create or overwrite a template.

Delete a template by name.

Destructive — requires user confirmation via MCP elicitation before running.

Render a template into ready-to-send subject and body text.

No side effects — caller is responsible for passing the rendered text to create_draft or update_draft (with send_now=True when ready to send).

With message_id, the original sender's display name and email, the original subject, and today's date are auto-populated as recipient_name, recipient_email, original_subject, and today. Without message_id, only today is auto-filled. User-supplied vars always override auto-fills on conflict.

Create a draft (fresh, reply, or forward). DOES NOT SEND.

To actually send, call draft_send(draft_id) as a separate step after reviewing/editing the draft. The split is intentional — sending requires its own explicit action and is the only path where the outbound allowlist policy is enforced.

Modes (driven by reply_to / forward_of):

• Neither: fresh draft (subject required).

• reply_to=<message_id>: reply draft. Mail.app auto-derives recipients and subject prefix unless overridden.

• forward_of=<message_id>: forward draft. Recipients default to empty (user must specify); subject prefixed with Fwd:.

Update an existing draft. DOES NOT SEND.

Patch semantics: only fields you pass change. None means "keep existing"; empty list/string means "clear". To actually send, call draft_send(draft_id) afterwards.

IMPORTANT: Mail.app forbids mutating saved drafts, so this is implemented as delete-and-recreate. The returned draft_id is a NEW id — use it for any subsequent draft_update or draft_send call. The id you passed in is stale after this call returns.

Delete (move to Trash) an existing draft. No send, no recovery expected — Mail.app moves the draft to Deleted Messages.

Send an existing draft. THIS IS THE ONLY SEND TOOL.

Hard policy gate: every recipient (to/cc/bcc) on the draft must match the outbound allowlist (see outbound_allowlist.py). If any recipient is off-list, the send is blocked and the draft is left INTACT for human review — you can edit it via draft_update or open Mail.app and send/discard manually.

Off-list recipients are detected BEFORE any destructive operation, so a blocked draft_send is a pure no-op on Mail.app state.

Send an HTML email directly. Does not save a draft first.

Body must be an HTML string. The email is composed via clipboard injection into Mail.app's rich-text compose window and sent immediately.

Outbound allowlist policy applies — all recipients must be on the allowlist.