Apple Mail.app integration for macOS. Read inbox, search emails, send emails, reply, and manage messages with fast direct access (no enumeration).
Interact with Mail.app via AppleScript and SQLite. Run scripts from: cd {baseDir}
| 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 "[email protected]" "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] |
Force Mail.app to check for new messages:
scripts/mail-refresh.sh # All accounts, wait up to 10s
scripts/mail-refresh.sh Google # Specific account only
scripts/mail-refresh.sh "" 5 # All accounts, max 5 seconds
scripts/mail-refresh.sh Google 0 # Google account, no wait
Smart sync detection:
Sync complete in 2s (+3 messages)Notes:
mail-list.sh does NOT auto-refresh — call mail-refresh.sh first if you need fresh dataList/search returns: ID | ReadStatus | Date | Sender | Subject
● = unread, blank = read⚠️ 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.
✨ Now safe even if Mail.app is running — copies database to temp file first.
scripts/mail-fast-search.sh "query" [limit] # ~50ms vs minutes
Previously required Mail.app to be quit. Now works anytime by copying the database to a temp file before querying.
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 multiplemail-mark-read.sh 123 456 - Mark multiple as readmail-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.
Delete emails:
scripts/mail-delete.sh 12345 # Delete one
scripts/mail-delete.sh 12345 12346 12347 # Delete multiple
Mark as read/unread:
scripts/mail-mark-read.sh 12345 12346 # Mark as read
scripts/mail-mark-unread.sh 12345 # Mark as unread
Bulk operations example:
# Find spam emails
scripts/mail-fast-search.sh "spam" 50 > spam.txt
# Extract IDs and delete them
grep "^[0-9]" spam.txt | cut -d'|' -f1 | xargs scripts/mail-delete.sh
scripts/mail-read.sh 12345 # Single email
scripts/mail-read.sh 12345 12346 12347 # Multiple emails (separated output)
Uses position-optimized lookup (~2s per message). Multiple emails are separated by ======== with a summary at the end.
| 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/ |
Database: ~/Library/Mail/V{9,10,11}/MailData/Envelope Index
Message lookup method (optimized):
Safety:
¹ Known limitation: Mail.app adds a leading blank line to sent emails. This is an AppleScript/Mail.app behavior that cannot be bypassed.