OpenParable
Skip to content
← Back to skills

Apple Mail

Apps & Automation
apple-mail

Apple Mail is an Agent Skill for apps & automation published in the YunjueTech/Yunjue-Agent repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

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

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/YunjueTech/Yunjue-Agent/blob/HEAD/example/cli/skills/apple-mail/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/apple-mail, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Apple Mail

Interact with Mail.app via AppleScript and SQLite.

Commands

CommandUsage
Refreshmail-refresh [account] [wait_seconds]
List recentmail-list [mailbox] [account] [limit]
Searchmail-search "query" [mailbox] [limit]
Fast searchmail-fast-search "query" [limit]
Read emailmail-read <message-id> [message-id...]
Deletemail-delete <message-id> [message-id...]
Mark readmail-mark-read <message-id> [message-id...]
Mark unreadmail-mark-unread <message-id> [message-id...]
Sendmail-send "[email protected]" "Subject" "Body" [from-account] [attachment] ¹
Replymail-reply <message-id> "body" [reply-all]
List accountsmail-accounts
List mailboxesmail-mailboxes [account]

Refreshing Mail

Force Mail.app to check for new messages:

mail-refresh                    # All accounts, wait up to 10s
mail-refresh Google             # Specific account only
mail-refresh "" 5               # All accounts, max 5 seconds
mail-refresh 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 does NOT auto-refresh — call mail-refresh 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 asUse
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.

mail-fast-search "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:

OperationSpeedNotes
mail-fast-search~50msSQLite query, fastest
mail-accounts<1sSimple AppleScript
mail-list1-3sAppleScript, direct mailbox access
mail-send1-2sCreates and sends message
mail-read~2sPosition-optimized lookup
mail-delete~0.5sPosition-optimized lookup
mail-mark-*~1.5sPosition-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 123 456 789 - Read multiple (separator between each)
  • mail-delete 123 456 789 - Delete multiple
  • mail-mark-read 123 456 - Mark multiple as read
  • mail-mark-unread 123 456 - Mark multiple as unread

⚠️ No auto-refresh: Scripts read cached data. Call mail-refresh first if you need latest emails.

Managing Emails

Delete emails:

mail-delete 12345                    # Delete one
mail-delete 12345 12346 12347        # Delete multiple

Mark as read/unread:

mail-mark-read 12345 12346           # Mark as read
mail-mark-unread 12345               # Mark as unread

Bulk operations example:

# Find spam emails
mail-fast-search "spam" 50 > spam.txt

# Extract IDs and delete them
grep "^[0-9]" spam.txt | cut -d'|' -f1 | xargs mail-delete

Reading Email Bodies

mail-read 12345              # Single email
mail-read 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

ErrorCause
Mail.app is not runningOpen Mail.app before running scripts
Account not foundInvalid account — check mail-accounts
Message not foundInvalid/deleted ID — get fresh from mail-list
Can't get mailboxInvalid name — check mail-mailboxes
Mail database not foundSQLite 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.