apple mail skill

read, write, search, and manage emails in macos mail.app via cli.

quick start

# verify setup (mail.app running, full disk access, dependencies)
.cursor/skills/apple-mail/scripts/check-setup.sh

# build the search index (required for search and content previews)
.cursor/skills/apple-mail/scripts/mail.sh build-index

# list recent emails with content previews
.cursor/skills/apple-mail/scripts/mail.sh list-recent --include-content

important: symlink path

this skill lives under .cursor/skills/apple-mail/ which may be a symlink. all script invocations should use the resolved path from this skill directory. run .cursor/skills/apple-mail/scripts/check-setup.sh to see resolved paths.

tool reference

all commands are invoked via .cursor/skills/apple-mail/scripts/mail.sh <command> [args].

all output is json with this contract:

{"success": bool, "data": ..., "error": ..., "warnings": [], "meta": {...}}

array arguments use space separation: --to a@b.com c@d.com --cc x@y.com

for detailed parameter docs and return shapes, see references/tool-reference.md.

workflows

triage inbox

1. list-recent --include-content -- scan recent emails with previews (note the message_id field in output)
2. read-email --message-id MID -- open specific email for full content (prefer --message-id over --id)
3. move-email --message-id MID --to Archive or delete-email --message-ids MID -- act on it

reply to an email

1. read-email --message-id MID -- read the email
2. reply-draft --message-id MID --body "..." [--reply-all] -- create reply draft
3. list-drafts -- confirm draft and get stable id
4. send-draft --id DRAFT_ID -- send

search and act

1. search --query "invoice" --scope all -- find matching emails
2. read-email --message-id MID -- read full content
3. take action (reply, forward, move, delete)

compose and send

1. compose-draft --account me@example.com --subject "Hello" --body "..." --to recipient@example.com
2. list-drafts — get stable draft id
3. amend-draft --id ID --body "revised text" — (optional) revise
4. send-draft --id ID — send

safety rules

1. always draft first -- never send without creating and confirming a draft
2. never delete without confirmation -- always confirm with the user before deletion
3. prefer --message-id over --id -- the RFC 2822 message-id (the message_id field from list commands) is stable across exchange syncs; integer ids can shift
4. verify draft ids -- draft ids may change after creation; always re-list drafts for stable ids
5. content previews are partial -- previews are the first ~5000 chars, not full content. use read-email for the complete message
6. exchange sync delay -- move operations on exchange accounts need ~3 s for server sync

id shift recovery

mail.app integer ids can change after exchange sync. use --message-id (the stable RFC 2822 header) to avoid this problem entirely:

• list commands (list-emails, list-recent, list-drafts) return both id (integer) and message_id (stable string) for each email
• read, delete, move, reply, and forward commands all accept --message-id as the preferred identifier
• --id (integer) still works as a fallback for backward compatibility

if a --message-id lookup fails (edge case), re-list the folder:

.cursor/skills/apple-mail/scripts/mail.sh list-emails --account EMAIL --folder FOLDER

background indexing

when --include-content is used and some emails aren't in the index, the system:

1. tries to find .emlx files on disk (instant)
2. falls back to jxa content fetch (up to 60 s)
3. if time runs out, spawns a background worker and returns partial results

check background progress: .cursor/skills/apple-mail/scripts/mail.sh index-status cancel if needed: .cursor/skills/apple-mail/scripts/mail.sh index-cancel

writing style

see references/writing-style.md for email composition guidelines.