Apple Mail.app integration for macOS. Read inbox, search emails, send emails, reply, and manage messages with fast direct access (no enumeration).

Apple Mail Interact with Mail.app via AppleScript and SQLite. Run scripts from: cd {baseDir} Commands Command Usage Refresh scripts/mail refresh.sh [account] [wait seconds] List recent scripts/mail list.sh [mailbox] [account] [limit] Search scripts/mail search.sh "query" [mailbox] [limit] Fast search scripts/mail fast search.sh "query" [limit] Read email scripts/mail read.sh <message id [message id...] Delete scripts/mail delete.sh <message id [message id...] Mark read scripts/mail mark read.sh <message id [message id...] Mark unread scripts/mail mark unread.sh <message id [message id...] Send scripts/mail send.sh "to@email.com" "Subject" "Body" [from account] [attachment] ¹ Reply scripts/mail reply.sh <message id "body" [reply all] List accounts scripts/mail accounts.sh List mailboxes scripts/mail mailboxes.sh [account] Refreshing Mail Force Mail.app to check for new messages: Smart sync detection: Script monitors database message count Returns early when sync completes (no changes for 2s) Reports new message count: Sync complete in 2s (+3 messages) Notes: Mail.app must be running (script will error if not) mail list.sh does NOT auto refresh — call mail refresh.sh first if you need fresh data Output Format List/search returns: ID ReadStatus Date Sender Subject ● = unread, blank = read Gmail Mailboxes ⚠️ Gmail special folders need [Gmail]/ prefix: Shows as Use Spam [Gmail]/Spam Sent Mail [Gmail]/Sent Mail All Mail [Gmail]/All Mail Trash [Gmail]/Trash Custom labels work without prefix. Fast Search (SQLite) ✨ Now safe even if Mail.app is running — copies database to temp file first. Previously required Mail.app to be quit. Now works anytime by copying the database to a temp file before querying. Performance Notes Speed by operation: Operation Speed Notes mail fast search.sh ~50ms SQLite query, fastest mail accounts.sh <1s Simple AppleScript mail list.sh 1 3s AppleScript, direct mailbox access mail send.sh 1 2s Creates and sends message mail read.sh ~2s Position optimized lookup mail delete.sh ~0.5s Position optimized lookup mail mark .sh ~1.5s Position optimized lookup Optimization technique: SQLite provides account UUID and approximate message position. AppleScript jumps directly to that position instead of iterating from the start. Batch operations supported: mail read.sh 123 456 789 Read multiple (separator between each) mail delete.sh 123 456 789 Delete multiple mail mark read.sh 123 456 Mark multiple as read mail mark unread.sh 123 456 Mark multiple as unread ⚠️ No auto refresh: Scripts read cached data. Call mail refresh.sh first if you need latest emails. Managing Emails Delete emails: Mark as read/unread: Bulk operations example: Reading Email Bodies Uses position optimized lookup (~2s per message). Multiple emails are separated by ======== with a summary at the end. Errors Error Cause Mail.app is not running Open Mail.app before running scripts Account not found Invalid account — check mail accounts.sh Message not found Invalid/deleted ID — get fresh from mail list.sh Can't get mailbox Invalid name — check mail mailboxes.sh Mail database not found SQLite DB missing — check ~/Library/Mail/V{9,10,11}/MailData/ Technical Details Database: ~/Library/Mail/V{9,10,11}/MailData/Envelope Index Message lookup method (optimized): 1. Query SQLite for account UUID, mailbox path, and approximate position 2. AppleScript accesses the specific account directly (no iteration) 3. Search starts at the approximate position (±5 messages buffer) 4. Falls back to full mailbox search only if position hint fails Safety: Fast search copies database to temp file before querying Safe to use even if Mail.app is running Delete/read/mark operations query live database but access is minimal Notes Message IDs are internal, get fresh ones from list/search Confirm recipient before sending AppleScript search is slow but comprehensive; SQLite is fast for metadata Delete/mark operations support bulk actions (pass multiple IDs) Always refresh before listing if you need the absolute latest emails ¹ Known limitation: Mail.app adds a leading blank line to sent emails. This is an AppleScript/Mail.app behavior that cannot be bypassed.

apple-mail