rbouschery 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
| Script | Purpose | Arguments |
|---|---|---|
list-accounts.sh |
List all email accounts | none |
list-mailboxes.sh |
List mailboxes/folders | [account] (optional) |
get-unread-count.sh |
Get unread email count | [account] [mailbox] (optional) |
Reading Emails
| Script | Purpose | Arguments |
|---|---|---|
get-emails.sh |
Get recent emails | [account] [mailbox] [limit] [include_content] [unread_only] |
get-email-by-id.sh |
Get specific email by ID | <id> [account] [mailbox] [include_content] |
search-emails.sh |
Search emails | <query> [account] [mailbox] [limit] |
Sending & Composing
| Script | Purpose | Arguments |
|---|---|---|
send-email.sh |
Send an email | <to> <subject> <body> [cc] [bcc] [from] |
create-draft.sh |
Create a draft email | <subject> <body> [to] [cc] [bcc] [from] |
create-reply-draft.sh |
Create reply to email | <message_id> <body> [reply_all] [account] [mailbox] |
send-draft.sh |
Send front-most draft | none |
Email Management
| Script | Purpose | Arguments |
|---|---|---|
archive-email.sh |
Archive an email | <message_id> [account] [mailbox] [archive_mailbox] |
delete-email.sh |
Delete an email | <message_id> [account] [mailbox] |
mark-read.sh |
Mark email as read | <message_id> [account] [mailbox] |
mark-unread.sh |
Mark email as unread | <message_id> [account] [mailbox] |
Output Format
Scripts use delimiters for structured output:
<<>>separates fields within a record|||separates multiple recordsERROR: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:
- Split by
|||to get individual records - Split each record by
<<>>to get fields - 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.