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 mailboxesSearch 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