apple-mail-mcp: Skill for Claude Code

AppleScript + Apple Mail Patterns

Emitting JSON from AppleScript

Scripts emit JSON via ASObjC + NSJSONSerialization (not pipe-delimited text). Use the _wrap_as_json_script(body) helper in mail_connector.py and parse responses with parse_applescript_json(result) from utils.py.

Tell-block contract: the body passed to _wrap_as_json_script must contain a tell application "Mail" ... end tell block and assign the final value to a variable named resultData (list, record, or scalar).

Record key gotcha — always quote name: Use |name|:(name of acc), never name:(name of acc). The bare form collides with NSObject's name selector and the key is silently dropped during NSDictionary conversion, leaving records without their name field.

missing value gotcha: NSJSONSerialization rejects missing value. For optional properties (e.g., email addresses of an account with none, unread count on some mailboxes), coerce before building the record:

set accEmails to email addresses of acc
if accEmails is missing value then set accEmails to {}

Error propagation: Do NOT wrap the tell-body in try / on error when you want typed exceptions (MailAccountNotFoundError, MailMessageNotFoundError, etc.). Let AppleScript errors bubble via stderr — _run_applescript maps them to the right exception type.

Gmail Label-Based System

Gmail doesn't support standard IMAP move operations. The update_message tool has a gmail_mode parameter (when used with destination_mailbox):

# Standard IMAP (Exchange, iCloud, etc.)
move message to destination_mailbox

# Gmail mode (copy + delete)
duplicate message to destination_mailbox
delete message  # Removes from source label

Bug story: Early versions silently failed when moving Gmail messages. The move appeared to succeed but the message stayed in the source mailbox. gmail_mode was added to handle this.

When to use: Always expose gmail_mode as an optional parameter on any tool that moves or archives messages.