Apple Mail Skill

This skill provides commands to interact with Apple Mail on macOS via AppleScript.

Available Scripts

All scripts are in the ../../scripts/ directory (relative to this file). Execute them via bash from the plugin root.

Account & Mailbox Management

Reading Emails

Sending & Composing

Email Management

Output Format

Scripts use delimiters for structured output:

• <<>> separates fields within a record
• ||| separates multiple records
• ERROR: prefix indicates an error message

Email Record Format

id<<>>subject<<>>sender<<>>to<<>>cc<<>>bcc<<>>dateSent<<>>isRead<<>>content|||

Usage Examples

List accounts

./scripts/list-accounts.sh

Get recent emails from INBOX

./scripts/get-emails.sh "" "INBOX" 10 false false

Get recent unread emails with content

./scripts/get-emails.sh "" "INBOX" 10 true true

Get specific email by ID

./scripts/get-email-by-id.sh 12345 "iCloud" "INBOX" true

Search emails

./scripts/search-emails.sh "meeting notes" "" "" 20

Send an email

./scripts/send-email.sh "recipient@example.com" "Subject" "Body text"

Send with CC and BCC

./scripts/send-email.sh "to@example.com" "Subject" "Body" "cc@example.com" "bcc@example.com"

Create a draft

./scripts/create-draft.sh "Draft Subject" "Draft body" "recipient@example.com"

Reply to an email

./scripts/create-reply-draft.sh 12345 "Thanks for your message!" false "iCloud" "INBOX"

Send the front-most draft

./scripts/send-draft.sh

Archive an email

./scripts/archive-email.sh 12345 "iCloud" "INBOX"

Mark as read/unread

./scripts/mark-read.sh 12345 "iCloud" "INBOX"
./scripts/mark-unread.sh 12345 "iCloud" "INBOX"

Parsing Output

When receiving email records, parse them like this:

1. Split by ||| to get individual records
2. Split each record by <<>> to get fields
3. Fields are: id, subject, sender, to, cc, bcc, dateSent, isRead, content

Example parsing in bash:

IFS='|||' read -ra emails <<< "$output"
for email in "${emails[@]}"; do
    IFS='<<>>' read -ra fields <<< "$email"
    id="${fields[0]}"
    subject="${fields[1]}"
    sender="${fields[2]}"
    # ... etc
done

Notes

• Scripts require macOS with Apple Mail configured
• Apple Mail must have at least one account set up
• First run may trigger macOS permission prompts for automation
• Empty optional arguments should be passed as empty strings ""
• For scripts that need arrays (multiple recipients), pass comma-separated values

Reference

For advanced AppleScript patterns and customization, see ./reference/applescript-patterns.md.