codewithbehnam/cc-docs/apple-mail

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

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