apple-mail · mitsuhiko — Claude Code skill: search emails and download attachments
Query Apple Mail locally on macOS, extract attachments, and read full messages from your AI agent. Read-only access to your email store.
Apache-2.0 260 installs ★ 3,224 updated 2026-09-27
npx skills add mitsuhiko/agent-stuff --skill apple-mail -a claude-codeWhat apple-mail does
apple-mail gives your agent the ability to search your local Apple Mail database, retrieve message details, and export attachments. It works with the Mail app's SQLite index and .emlx files on disk.
The skill runs a bash script that supports searching by sender, recipient, subject, body text, date range, mailbox, and message flags. You can retrieve message metadata with info, read full RFC822 format emails with read, or extract attachments to a temp directory with attachment. Search results come back as a pipe-delimited table showing ID, sender, subject, received date, and attachment count. Filters include --unread, --flagged, --has-attachment, and date ranges with --after and --before.
Partially downloaded messages (stored as .partial.emlx) are flagged in output. Attachments are extracted to /tmp/ with a timestamp, and the script prints the directory path for your agent to use.
What it helps with
- search emails by sender, recipient, subject or date
- download attachments from specific messages
- read the full RFC822 source of an email with headers
- filter unread or flagged messages from a mailbox
- get a summary of all mailboxes and message counts
Example prompts for the agent
- Find all emails from [email protected] about invoices and extract their attachments
- Show unread messages in INBOX with attachments from February onwards
- Read the complete raw email 783660 including all headers
How to install apple-mail
1Skills CLI (Vercel)
npx skills add mitsuhiko/agent-stuff --skill apple-mail -a claude-code2Manually: put the files in place
~/.claude/skills/apple-mail/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/apple-mail/
1Skills CLI (Vercel)
npx skills add mitsuhiko/agent-stuff --skill apple-mail -a codex2Manually: put the files in place
.agents/skills/apple-mail/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add mitsuhiko/agent-stuff --skill apple-mail -a cursor2Manually: put the files in place
.cursor/skills/apple-mail/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install mitsuhiko/agent-stuff skills/apple-mail2Manually: put the files in place
.github/skills/apple-mail/SKILL.md1Skills CLI (Vercel)
npx skills add mitsuhiko/agent-stuff --skill apple-mail -a gemini-cli2Platform CLI
gemini skills install https://github.com/mitsuhiko/agent-stuff --path skills/apple-mailManually: put the files in place
.devin/skills/apple-mail/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add mitsuhiko/agent-stuff --skill apple-mail -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about apple-mail
How do I install apple-mail in Claude Code?
Run npx skills add mitsuhiko/agent-stuff --skill apple-mail -a claude-code, then verify the file at ~/.claude/skills/apple-mail/SKILL.md.
What does apple-mail do?
It lets your agent search, read, and download attachments from Apple Mail's local storage on macOS. The script queries Mail's database and reads .emlx files without modifying any messages.
Can I combine search filters?
Yes. You can mix --from, --to, --subject, --after, --before, --unread, --flagged, and --has-attachment in one search command.
Source text
SKILL.md · Apache-2.0
--- name: apple-mail description: "Search, read, and extract attachments from Apple Mail's local storage. Query emails by sender, recipient, subject, body, date, mailbox, and flags. Read raw RFC822 messages and extract file attachments." --- # Apple Mail Skill Search, read, and extract attachments from Apple Mail's local storage on macOS. ## Tool `apple-mail.sh` — a bash script that queries the Apple Mail SQLite envelope index and reads `.emlx` files from disk. **Read-only** — it never modifies mail data. ## Quick Reference ```bash TOOL=~/Development/agent-stuff/skills/apple-mail/apple-mail.sh # Search emails $TOOL search --from "peter@" --subject "dinner" --limit 5 $TOOL search --after 2026-02-01 --has-attachment $TOOL search --body "invoice" --mailbox "INBOX" --unread $TOOL search --to "armin@" --before 2025-12-31 # Show message metadata, recipients, attachments, and summary $TOOL info 783660 # Read the raw RFC822 email (headers + body) $TOOL read 783660 # Extract attachments to a temp directory (prints the path) $TOOL attachment 783660 # all attachments $TOOL attachment 783660 "Rechnung.pdf" # specific file # List all mailboxes with counts $TOOL mailboxes ``` ## Search Options | Flag | Description | |------|-------------| | `--from <addr>` | Sender address substring | | `--to <addr>` | Recipient address substring | | `--subject <text>` | Subject substring | | `--body <text>` | Body/summary text substring | | `--mailbox <name>` | Mailbox URL substring (e.g. `INBOX`, `Sent`, `Trash`) | | `--after <YYYY-MM-DD>` | Received after date | | `--before <YYYY-MM-DD>` | Received before date | | `--unread` | Only unread messages | | `--flagged` | Only flagged messages | | `--has-attachment` | Only messages with attachments | | `--limit <n>` | Max results (default: 20) | ## Output Format - `search` returns pipe-delimited table with header row: `id|sender|sender_name|subject|received|status|flagged|mailbox|attachments` - `info` returns structured metadata sections - `read` outputs raw RFC822 email to stdout - `attachment` prints the temp directory path to stdout, file listing to stderr ## Notes - Message IDs are Apple Mail internal ROWIDs (integers), shown in the `id` column - `.partial.emlx` files contain headers only (body not downloaded); `read` warns about this - Attachments are copied to a temp directory under `/tmp/`; clean up when done - The `body` search queries the `summaries` table (Apple Mail's plaintext preview), not the full email body - Mailbox URLs are percent-encoded (e.g., `%5BGmail%5D` = `[Gmail]`, `%20` = space) - Deleted messages are excluded from search by default
© mitsuhiko · Apache-2.0 · mitsuhiko/agent-stuff
Similar skills
All skills for Notes, tasks and projects →apple-mail by other authors comes first.