apple mail jxa

Managing emails on macOS often requires manual intervention or clunky UI scripting. This skill provides a high-performance interface for Apple Mail using native JXA and direct SQLite indexing. It allows for fast, programmatic access to accounts, mailboxes, and messages without the overhead of external wrappers.

What it does

• Account discovery retrieves all enabled macOS Mail accounts and their unique identifiers.
• Deep mailbox mapping traverses nested mailbox structures to locate specific folders by path.
• High-speed search uses a hybrid approach with direct SQLite queries to the local Envelope Index for instant metadata retrieval.
• Message management handles reading bodies, drafting, replying, and forwarding with strict privacy bounds.
• State mutation updates read status, flags, and moves or deletes messages with explicit confirmation workflows.

How it works

1. Discovery: The agent identifies the active Mail accounts and mailbox hierarchies to establish valid references.
2. Search: For broad queries, it queries the local Envelope Index via sqlite3 in read-only mode to find message IDs.
3. Hydration: It resolves SQLite results back into Mail.app objects to ensure data freshness before any operations.
4. Action: It executes JXA commands for drafting or state changes, always creating a visible draft for outgoing mail to ensure user oversight.

Frameworks & tools

This skill utilizes macOS native JavaScript for Automation (JXA), the Foundation framework via bridge, and the system SQLite3 binary.

Why this beats prompting it yourself

Writing reliable JXA for Mail is notoriously difficult due to weird AppleEvent behaviors and slow collection filtering. This skill implements a sophisticated hybrid backend that bypasses slow AppleScript loops by querying the local database directly while maintaining the safety of the official API for writes.

Use cases

• Automating the sorting of high-volume mailboxes based on sender or subject patterns.
• Summarizing recent unread threads from specific clients or projects.
• Drafting standardized replies for confirmation or follow-up workflows.
• Searching years of archives instantly using direct database indexing.

Known limitations

Requires macOS Automation permissions for Mail.app and Full Disk Access for the terminal to read the SQLite index. It does not support modifying account settings or credentials.