Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add mitsuhiko/agent-stuff --skill apple-mail -a claude-code
Open on GitHub

What 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-code

2Manually: put the files in place

~/.claude/skills/apple-mail/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/apple-mail/

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.

apple-mail sundial-org This skill connects an agent to Apple Mail.app to search, read, send, and manage messages. Use it to handle email tasks through your coding agent. CX Codex +1 356installs apple-mail rbouschery Drives Apple Mail on macOS with AppleScript: read, search, send and archive mail from scripts. Triaging a mailbox happens without touching the Mail window. CX Codex +1 1,400installs Apple Mail MCP imdinu An MCP server for reading and searching Apple Mail. Body search runs over an FTS5 index that covers the whole mailbox, not just recent messages. CX Codex +1 ★ 76repo stars Apple Mail mgcrea MCP server connecting macOS Apple Mail to coding agents. It searches local messages and reads email bodies directly on your Mac without external IMAP logins. CX Codex +1 ★ 6repo stars zoho-mail membrane Skill for managing emails, contacts, tasks, labels and calendars in Zoho Mail via Membrane CLI. CX Codex +1 181installs WireCat Mail WireCatLabs WireCat Mail — an MCP server for Claude Code and Codex syncs mailbox messages into local storage, enabling AI assistants to search, read, organize, draft, and send emails via IMAP and SMTP. CX Codex +1 ★ 3repo stars email-management-expert sundial-org email-management-expert guides your coding agent through Apple Mail triage and folder sorting via MCP tools. Helpful when reaching Inbox Zero or finding misplaced threads. CX Codex +1 514installs Apple Shortcuts Integration Claude Office Skills Apple Shortcuts Integration is a Claude Code skill that creates and runs Apple Shortcuts for iOS and macOS automation, including reminders, notes, and calendar workflows. CX Codex +1 4,900installs

From the same set16

The whole set →
ghidra Runs headless Ghidra analysis to decompile executables into C and export strings, symbols, or call graphs. Helpful when reverse engineering firmware or binaries directly from the terminal. CX Codex +1 706installs web-browser web-browser hands your agent a real Chrome: page navigation, clicks, form filling, screenshots, console and network inspection. Useful when a live browser beats scraping HTML. CX Codex +1 685installs github Teaches the agent to work with GitHub through the gh CLI: pull requests, CI runs, issues and raw API queries. CX Codex +1 507installs tmux Runs interactive CLI sessions inside tmux using an isolated socket. Helpful when an agent must feed keystrokes into Python or lldb and scrape pane output. CX Codex +1 425installs uv Replaces pip, python, and venv with uv, a fast package manager and Python runtime. Run scripts via uv run, add dependencies with uv add, embed requirements directly in scripts. CX Codex +1 251installs librarian librarian caches remote Git repositories locally and refreshes them when referenced again. Useful when an agent needs to inspect external source code. CX Codex +1 170installs sentry Connects your coding agent to the Sentry API to inspect production crashes, examine stack traces, check breadcrumbs, and query system logs. CX Codex +1 136installs native-web-search native-web-search — a skill that runs a fast model with built-in web search and returns a concise summary with full source URLs. Useful when you need current information while coding. CX Codex +1 134installs

Project sponsors

Companies that keep this analytics open