apple-mail

Apple Mail Skill

Overview

This skill enables interaction with Apple Mail on macOS through AppleScript (osascript). It provides capabilities to list accounts, browse mailboxes, retrieve message lists, and read full message content.

Prerequisites

• macOS system
• Apple Mail app installed and configured
• At least one mail account set up in Apple Mail
• Apple Mail must be running when using this skill

Quick Start

List Available Accounts

python3 {baseDir}/scripts/list_accounts.py

List Mailboxes for an Account

python3 {baseDir}/scripts/list_mailboxes.py "Account Name"

Get Messages from a Mailbox

# Get 10 most recent messages (default)
python3 {baseDir}/scripts/get_messages.py "Account Name" "INBOX"

# Get specific number of messages
python3 {baseDir}/scripts/get_messages.py "Account Name" "INBOX" --limit 20

Read Full Message Content

python3 {baseDir}/scripts/get_message_content.py "MESSAGE_ID"

Typical Workflows

Workflow 1: Browse Mail

1. List accounts to see what's available
2. Choose an account and list its mailboxes
3. Get messages from desired mailbox
4. Read full content of specific messages

Workflow 2: Search for Specific Messages

1. Get messages from target mailbox with appropriate limit
2. Review subjects and senders from the list
3. Identify message IDs of interest
4. Read full content of relevant messages

Script Reference

list_accounts.py

Lists all configured mail accounts in Apple Mail.

Output format: JSON array of account names

{
  "accounts": ["iCloud", "Gmail", "Work"],
  "count": 3
}

list_mailboxes.py <account_name>

Lists all mailboxes (folders) for a specific account.

Arguments:

• account_name: Name of the mail account (from list_accounts.py)

Output format: JSON array of mailbox names

{
  "account": "iCloud",
  "mailboxes": ["INBOX", "Sent", "Drafts", "Trash", "Archive"],
  "count": 5
}

get_messages.py <account_name> <mailbox_name> [--limit N]

Retrieves message list from a specific mailbox.

Arguments:

• account_name: Name of the mail account
• mailbox_name: Name of the mailbox (e.g., "INBOX", "Sent")
• --limit N: Optional, max number of messages to retrieve (default: 10)

Output format: JSON array with message metadata

{
  "account": "iCloud",
  "mailbox": "INBOX",
  "messages": [
    {
      "id": "123456",
      "subject": "Meeting Tomorrow",
      "sender": "colleague@example.com",
      "date_sent": "Monday, January 27, 2026 at 10:30:00 AM",
      "date_received": "Monday, January 27, 2026 at 10:30:05 AM",
      "read_status": false,
      "message_size": 2048
    }
  ],
  "count": 1
}

get_message_content.py <message_id>

Retrieves full content of a specific message.

Arguments:

• message_id: Message ID from get_messages.py output

Output format: JSON with full message details

{
  "subject": "Meeting Tomorrow",
  "sender": "colleague@example.com",
  "content": "Hi, let's meet tomorrow at 2 PM...",
  "date_sent": "Monday, January 27, 2026 at 10:30:00 AM"
}

Common Patterns

Pattern: Find Unread Messages

1. Get messages from INBOX
2. Filter results where read_status is false
3. Read content of unread messages

Pattern: Check Sent Messages

1. List mailboxes to find "Sent" or "Sent Messages"
2. Get messages from sent mailbox
3. Review what was sent recently

Pattern: Search Multiple Mailboxes

1. List all mailboxes for account
2. Iterate through mailboxes of interest
3. Get messages from each
4. Aggregate and present results

Error Handling

All scripts output errors in a consistent format:

{
  "error": "Error description",
  "details": "Additional context if available"
}

Common errors:

• Apple Mail not running: Start the Mail app
• Invalid account name: Check spelling, account names are case-sensitive
• Invalid mailbox name: Use exact name from list_mailboxes.py
• Message not found: Message may have been deleted or moved

Important Notes

• Case sensitivity: Account and mailbox names are case-sensitive
• Mail app must be running: All scripts require Apple Mail to be open
• Permissions: First use may prompt for automation permissions in System Preferences
• Performance: Large mailboxes may take longer to query; use --limit to constrain results
• Message IDs: Message IDs are persistent unless the message is deleted

Limitations

• Only works on macOS
• Requires Apple Mail (doesn't work with other mail clients)
• Cannot send or delete messages (read-only operations)
• Cannot modify message properties (flags, folders, etc.)
• Limited to mailboxes directly under accounts (nested folders may not be accessible)