apple-mail
Interact with Apple Mail on macOS. Use for reading, sending, searching, and managing emails.
Resources
2Install
npx skillscat add rbouschery/marketplace/apple-mail Install via the SkillsCat registry.
SKILL.md
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.shGet recent emails from INBOX
./scripts/get-emails.sh "" "INBOX" 10 false falseGet recent unread emails with content
./scripts/get-emails.sh "" "INBOX" 10 true trueGet specific email by ID
./scripts/get-email-by-id.sh 12345 "iCloud" "INBOX" trueSearch emails
./scripts/search-emails.sh "meeting notes" "" "" 20Send 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.shArchive 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
doneNotes
- 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.
Install
npx skillscat add rbouschery/marketplace/apple-mail Install via the SkillsCat registry.