✓ Verified 📁 File Management ✓ Enhanced Data

Apple Mail

Apple Mail.app integration for macOS.

Rating: 4.4 (10 reviews)
Downloads: 1,342 downloads
Version: 1.0.0

Overview

Apple Mail.app integration for macOS.

Complete Documentation

View Source →

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...]
Delete	scripts/mail-delete.sh [message-id...]
Mark read	scripts/mail-mark-read.sh [message-id...]
Mark unread	scripts/mail-mark-unread.sh [message-id...]
Send	scripts/mail-send.sh "[email protected]" "Subject" "Body" [from-account] [attachment] ¹
Reply	scripts/mail-reply.sh "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:

bash

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:

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.

bash

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.

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:

bash

scripts/mail-delete.sh 12345                    # Delete one
scripts/mail-delete.sh 12345 12346 12347        # Delete multiple

Mark as read/unread:

bash

scripts/mail-mark-read.sh 12345 12346           # Mark as read
scripts/mail-mark-unread.sh 12345               # Mark as unread

Bulk operations example:

bash

# 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

Reading Email Bodies

bash

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.

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):

Query SQLite for account UUID, mailbox path, and approximate position
AppleScript accesses the specific account directly (no iteration)
Search starts at the approximate position (±5 messages buffer)
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.

Installation

Terminal bash


openclaw install apple-mail

Copied!

💻Code Examples

scripts/mail-refresh.sh Google 0 # Google account, no wait

scriptsmail-refreshsh-google-0--google-account-no-wait.txt

**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.

scripts/mail-fast-search.sh "query" [limit] # ~50ms vs minutes

scriptsmail-fast-searchsh-query-limit--50ms-vs-minutes.txt

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:**

example.sh

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

example.sh

# 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