apple-mail

name	apple-mail
description	Use Apple Mail from Codex through the local Apple Mail MCP plugin. Trigger for mailbox discovery, message search/read/context retrieval, newest email, drafting or sending mail, and mail archive/delete/move/junk workflows.

Apple Mail

Use this skill when a task should access local Apple Mail.

Fast routing

• First use, a new Mac, or permission failures: mail_request_permissions.
• Exact lookup or newest/latest email: mail_search, then mail_read only if the user needs body/details.
• Broad mail context such as "what matters about X": mail_retrieve_context.
• Writes: call the mutating tool with dryRun: true for a preview, then repeat with confirm: true only after the user clearly confirms.

First-run setup behavior

• If the user asks to set up the plugin, mentions a fresh clone/new Mac, or hits an access error, call mail_request_permissions before any mail search/read/write tool.
• Treat permission output as an onboarding checklist: summarize the next step in plain language, ask the user to approve macOS prompts or System Settings toggles when needed, then retry only after they say it is done.
• Do not use real mail content to test permissions. The setup tool is the privacy-light probe.

Workflow

• Prefer mail_retrieve_context for broad or fuzzy requests like "find what matters about X" or "use my email as context".
• Use mail_search when the user needs message candidates or handles. Use explicit scopes for sent, archive, trash, and junk when the request names those areas.
• For sent-mail questions like "what did I send to X", use scope: "sent" plus recipient.
• Use subject for exact known-subject lookups; broad query is for metadata terms.
• Use mail_read only for selected messages and keep body limits tight.
• Use mail_compose for drafts.
• Use mail_send, mail_archive, mail_delete, mail_junk, mail_move, and mail_undo_move only when the configured write guard allows it.
• Treat delete as moving messages to Trash/Deleted Items, not permanent deletion.
• Keep undo tokens returned by move/archive/delete/junk actions if the user may want to reverse the move.

Examples

Newest email metadata, then a tight body read only if needed:

mail_search({"scope":"inbox","limit":1})
mail_read({"handles":["<handle-from-search>"],"maxBodyChars":1200})

Find messages the user sent to someone:

mail_search({"scope":"sent","recipient":"[e-mail]","limit":10})

Retrieve broad context for a topic without dumping full threads:

mail_retrieve_context({"scope":"all","query":"Princeton exchange","topK":5,"maxBodyChars":2000})

Create a visible draft:

mail_compose({"to":["[e-mail]"],"subject":"Follow up","body":"Hi ...","visible":true})

Preview, then send only after confirmation:

mail_send({"to":["[e-mail]"],"subject":"Follow up","body":"Hi ...","dryRun":true})
mail_send({"to":["[e-mail]"],"subject":"Follow up","body":"Hi ...","confirm":true})

Guarded archive/delete/move pattern:

mail_archive({"handles":["<handle>"],"dryRun":true})
mail_archive({"handles":["<handle>"],"confirm":true})
mail_undo_move({"undoTokens":["<undo-token>"],"confirm":true})

Access mode

• APPLE_MAIL_WRITE_MODE=ask is the default. Mutating tools return a preview or target summary unless the call includes confirm: true.
• APPLE_MAIL_WRITE_MODE=direct means full local write access.

Privacy

Do not paste large private email bodies unless the user explicitly asks. Prefer concise summaries and cite handles, subjects, senders, and dates.