apple-mail
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.
- Installs
- 253
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/mitsuhiko/agent-stuff --skill apple-mail- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads apple-mail automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
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
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
searchreturns pipe-delimited table with header row:id|sender|sender_name|subject|received|status|flagged|mailbox|attachmentsinforeturns structured metadata sectionsreadoutputs raw RFC822 email to stdoutattachmentprints the temp directory path to stdout, file listing to stderr
Notes
- Message IDs are Apple Mail internal ROWIDs (integers), shown in the
idcolumn .partial.emlxfiles contain headers only (body not downloaded);readwarns about this- Attachments are copied to a temp directory under
/tmp/; clean up when done - The
bodysearch queries thesummariestable (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
FAQ
What does the apple-mail skill do?
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.
How do I install apple-mail?
Run npx skills add https://github.com/mitsuhiko/agent-stuff --skill apple-mail in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/apple-mail/ (personal) or .claude/skills/apple-mail/ (project).
Which AI agents can use apple-mail?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is apple-mail safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains apple-mail?
It is published by mitsuhiko in mitsuhiko/agent-stuff. It has 253 recorded installs.
More from mitsuhiko/agent-stuff
openscad
mitsuhiko/agent-stuff
Create and render OpenSCAD 3D models. Generate preview images from multiple angles, extract customizable parameters, validate syntax, and export STL files for 3D printing platforms like MakerWorld.
web-browser
mitsuhiko/agent-stuff
Automate and interact with web pages through Chrome or Chromium using the Chrome DevTools Protocol (CDP): navigate, click, fill forms, inspect content, take screenshots, and debug console or network activity. Use when an agent needs a real browser. Prefer headless Chrome unless visible browser interaction is required.
ghidra
mitsuhiko/agent-stuff
Reverse engineer binaries using Ghidra's headless analyzer. Decompile executables, extract functions, strings, symbols, and analyze call graphs without GUI.
github
mitsuhiko/agent-stuff
Interact with GitHub using the gh CLI. Use gh issue, gh pr, gh run, and gh api for issues, PRs, CI runs, and advanced queries.
tmux
mitsuhiko/agent-stuff
Remote control tmux sessions for interactive CLIs (python, gdb, etc.) by sending keystrokes and scraping pane output.
commit
mitsuhiko/agent-stuff
Read this skill before making git commits
Popular other skills
hyperframes-cli
heygen-com/hyperframes
The HyperFrames CLI by job - scaffold, check, look at frames, edit the timeline, preview, render locally or in the cloud, publish, project history - plus reading its JSON and recovering from build or render failures.
triage
mattpocock/skills
Move issues and external PRs through a state machine of triage roles, categorise, verify, grill if needed, and write agent-ready briefs.
ask-matt
mattpocock/skills
Ask which skill or flow fits your situation. A router over the skills in this repo.
to-questionnaire
mattpocock/skills
Turn a decision you can't fully answer into a questionnaire for someone else to fill in.
loop-me
mattpocock/skills
Grill me about specs for the workflows I want to build, within this workspace.