Apple Mail
Overview
This skill is the macOS Mail.app entry point. It implements mail.* automation
with JSON output designed for agent workflows.
When to Use
- User asks to manage Apple Mail on this Mac
- User wants to inspect inboxes, triage messages, archive clutter, or move mail between folders
- User specifically wants local Mail.app behavior, not Gmail web UI or IMAP libraries
Do not use this skill for webmail sites opened in a browser.
Command Surface
The helper lives next to this skill at scripts/apple_apps.py.
Read-only commands:
python3 scripts/apple_apps.py mail accounts
python3 scripts/apple_apps.py mail mailboxes --account "iCloud"
python3 scripts/apple_apps.py mail recent --account "SYSU" --limit 1 --include-read
python3 scripts/apple_apps.py mail triage-meta --account "SYSU" --mailbox-path "INBOX" --limit 5 --include-read --on-date "2026-03-18"
python3 scripts/apple_apps.py mail search --account "SYSU" --query "invoice" --limit 20
python3 scripts/apple_apps.py mail search --account "SYSU" --query "Beta view" --limit 10 --include-read --include-body
python3 scripts/apple_apps.py mail read --id 141819 --account "SYSU" --mailbox-path "INBOX"
Mutation commands:
python3 scripts/apple_apps.py mail mark --id 141819 --account "SYSU" --mailbox-path "INBOX" --read true
python3 scripts/apple_apps.py mail move --id 141819 --account "SYSU" --mailbox-path "INBOX" --to-mailbox "Archive"
python3 scripts/apple_apps.py mail archive --id 141819 --account "SYSU" --mailbox-path "INBOX"
python3 scripts/apple_apps.py mail delete --id 141819 --account "SYSU" --mailbox-path "INBOX"
Workflow
- For daily inbox triage, start with
triage-meta.
- For point lookups and thread recovery, use
search.
- For one-message inspection, use
recent.
- Capture the returned
id, account, and mailboxPath.
- Pass those exact values into
read, mark, move, archive, or delete.
Current Limits
- The fastest path for daily message triage is
triage-meta, which reads lightweight metadata from headers without loading message bodies.
search now prefers lightweight thread-aware matching when --include-body is not set. It can use subject, sender, recipients, message ids, and reply-chain headers to return both direct hits and nearby thread context.search --include-body now uses a two-stage path: lightweight recall first, then body reads for only a small candidate set. This is much more practical for recent-thread recovery, but it is still not a full-mailbox text index.recent is still useful for quick one-message inspection, especially recent --account ... --limit 1 --include-read.read, mark, move, archive, and delete are verified for top-level mailbox paths such as INBOX and Archive.- After
move or archive, Mail may assign a new internal numeric id; refresh it with another recent or read before the next mutation.
Safety Rules
- Default to read-only exploration first.
- Before destructive actions (
move, archive, delete), identify the exact target messages from recent or search.
- Prefer
mailboxPath over mailbox when a folder name could be ambiguous.
1---2name: apple-mail3description: Use only for Apple Mail or Mail.app tasks on macOS, including listing accounts and mailboxes, inspecting or searching messages, and reading, marking, archiving, moving, or deleting mail. Do not use for other Apple native apps, webmail, IMAP-only work, or generic macOS automation.4---56# Apple Mail78## Overview910This skill is the macOS Mail.app entry point. It implements `mail.*` automation11with JSON output designed for agent workflows.1213## When to Use1415- User asks to manage Apple Mail on this Mac16- User wants to inspect inboxes, triage messages, archive clutter, or move mail between folders17- User specifically wants local Mail.app behavior, not Gmail web UI or IMAP libraries1819Do not use this skill for webmail sites opened in a browser.2021## Command Surface2223The helper lives next to this skill at `scripts/apple_apps.py`.2425Read-only commands:2627```bash28python3 scripts/apple_apps.py mail accounts29python3 scripts/apple_apps.py mail mailboxes --account "iCloud"30python3 scripts/apple_apps.py mail recent --account "SYSU" --limit 1 --include-read31python3 scripts/apple_apps.py mail triage-meta --account "SYSU" --mailbox-path "INBOX" --limit 5 --include-read --on-date "2026-03-18"32python3 scripts/apple_apps.py mail search --account "SYSU" --query "invoice" --limit 2033python3 scripts/apple_apps.py mail search --account "SYSU" --query "Beta view" --limit 10 --include-read --include-body34python3 scripts/apple_apps.py mail read --id 141819 --account "SYSU" --mailbox-path "INBOX"35```3637Mutation commands:3839```bash40python3 scripts/apple_apps.py mail mark --id 141819 --account "SYSU" --mailbox-path "INBOX" --read true41python3 scripts/apple_apps.py mail move --id 141819 --account "SYSU" --mailbox-path "INBOX" --to-mailbox "Archive"42python3 scripts/apple_apps.py mail archive --id 141819 --account "SYSU" --mailbox-path "INBOX"43python3 scripts/apple_apps.py mail delete --id 141819 --account "SYSU" --mailbox-path "INBOX"44```4546## Workflow47481. For daily inbox triage, start with `triage-meta`.492. For point lookups and thread recovery, use `search`.503. For one-message inspection, use `recent`.514. Capture the returned `id`, `account`, and `mailboxPath`.525. Pass those exact values into `read`, `mark`, `move`, `archive`, or `delete`.5354## Current Limits5556- The fastest path for daily message triage is `triage-meta`, which reads lightweight metadata from headers without loading message bodies.57- `search` now prefers lightweight thread-aware matching when `--include-body` is not set. It can use subject, sender, recipients, message ids, and reply-chain headers to return both direct hits and nearby thread context.58- `search --include-body` now uses a two-stage path: lightweight recall first, then body reads for only a small candidate set. This is much more practical for recent-thread recovery, but it is still not a full-mailbox text index.59- `recent` is still useful for quick one-message inspection, especially `recent --account ... --limit 1 --include-read`.60- `read`, `mark`, `move`, `archive`, and `delete` are verified for top-level mailbox paths such as `INBOX` and `Archive`.61- After `move` or `archive`, Mail may assign a new internal numeric `id`; refresh it with another `recent` or `read` before the next mutation.6263## Safety Rules6465- Default to read-only exploration first.66- Before destructive actions (`move`, `archive`, `delete`), identify the exact target messages from `recent` or `search`.67- Prefer `mailboxPath` over `mailbox` when a folder name could be ambiguous.
gaofeng21cn