apple-mail: an agent skill that gives AI assistants full control over macOS Mail.app

I open-sourced an agent skill that gives AI coding assistants full control over macOS Mail.app: read, search, compose, reply, forward, move, delete, and label emails without leaving the editor.

It ships as a self-contained skill directory. Drop it into your agent's skill folder (e.g. .cursor/skills/) and the agent can triage your inbox, draft replies, and organise mail on your behalf. It works with Cursor, Claude Code, or any agent that can invoke shell commands.

Why?

Scripting Bridge calls to Mail.app are slow (seconds per message). This skill reads .emlx files directly from disk (~5 ms per message) and maintains a SQLite FTS5 search index for fast full-text search across body, subject, and sender.

Highlights

• Disk-first reads: parses .emlx files directly (~5 ms per message vs seconds via the scripting bridge)
• FTS5 search: SQLite full-text search index across body, subject, and sender
• Exchange-safe deletes: uses RFC Message-ID so it works reliably with Exchange accounts
• Draft-first sending: compose and reply always create drafts first; nothing sends without explicit confirmation
• Dry-run support: destructive operations (delete, amend-subject) support --dry-run to preview changes

Commands

All commands go through scripts/mail.sh and return structured JSON:

list-accounts, list-folders, list-recent, list-emails, list-drafts, read-email, search, compose-draft, amend-draft, send-draft, reply-draft, forward-draft, delete-email, delete-draft, move-email, amend-subject, add-label, build-index

Setup

cp -r apple-mail /path/to/project/.cursor/skills/

On first use, mail.sh auto-creates a micromamba environment with Python 3.11 and installs dependencies.

Requirements: macOS with Mail.app configured, micromamba, Full Disk Access for Terminal.

Links

• GitHub: Don-Yin/apple-mail
• License: MIT

Feedback and PRs welcome!