Comprehensive guide for accessing and automating Apple Mail using AppleScript, including reading emails, sending messages, and managing mailboxes.
apple-mail follows the SKILL.md standard. Use the install command to add it to your agent stack.
---
name: apple-mail
description: Comprehensive guide for accessing and automating Apple Mail using AppleScript, including reading emails, sending messages, and managing mailboxes.
---
# Apple Mail AppleScript Skill
This skill provides comprehensive guidance on using AppleScript to automate Apple Mail operations, including reading emails, sending messages, and managing mailboxes.
## Core Principles
1. **Access mailboxes through account objects** - Don't try to access `inbox` directly on accounts
2. **Iterate through mailboxes to find the right one** - Mailbox names can vary (INBOX, Inbox, etc.)
3. **Use account name matching** - Match on account name rather than email address property
4. **Handle errors gracefully** - AppleScript errors can be cryptic, use trial and error with different approaches
## Common Query Patterns
### 1. List All Mail Accounts
Always start by listing accounts to verify the account exists and get the correct name:
```applescript
osascript <<'EOF'
tell application "Mail"
set accountNames to {}
repeat with acc in accounts
set end of accountNames to (name of acc)
end repeat
return accountNames as string
end tell
EOF
```
**Example output:**
```
MonzoiCloudbrunofdcampos@gmail.commmbcfields@gmail.comcampos.bruno.fd@gmail.com
```
### 2. Read Last N Emails from an Account
The **correct pattern** for accessing emails from a specific account:
```applescript
osascript <<'EOF'
tell application "Mail"
set targetAccount to account "email@example.com"
set allMailboxes to every mailbox of targetAccount
repeat with mbox in allMailboxes
if name of mbox is "INBOX" or name of mbox is "Inbox" then
set inboxMsgs to messages of mbox
set msgCount to count of inboxMsgs
set numToFetch to 5
if msgCount < 5 then set numToFetch to msgCount
set output to ""
repeat with i from 1 to numToFetch
set msg to item i of inboxMsgs
set output to output & "Email #" & i & return
set output to output & "Subject: " & subject of msg & return
set output to output & "From: " & sender of msg & return
set output to output & "Date: " & (date received of msg as string) & return
set output to output & return & "---" & return & return
end repeat
return output
end if
end repeat
return "Inbox not found"
end tell
EOF
```
**Key lessons from trial and error:**
- ❌ **WRONG:** `inbox of targetAccount` (doesn't work, causes error -1728)
- ❌ **WRONG:** `address of acc` (address property doesn't exist reliably)
- ✅ **CORRECT:** `every mailbox of targetAccount` then iterate to find "INBOX" or "Inbox"
### 3. Read Email Content
Get the full body content of a specific email:
```applescript
osascript <<'EOF'
tell application "Mail"
set targetAccount to account "email@example.com"
set allMailboxes to every mailbox of targetAccount
repeat with mbox in allMailboxes
if name of mbox is "INBOX" or name of mbox is "Inbox" then
set msg to item 1 of messages of mbox
set emailContent to content of msg
return emailContent
end if
end repeat
end tell
EOF
```
### 4. Send an Email
Create and send a new email:
```applescript
osascript <<'EOF'
tell application "Mail"
set newMessage to make new outgoing message with properties {subject:"Your Subject", content:"Your email body here", visible:true}
tell newMessage
make new to recipient at end of to recipients with properties {address:"recipient@example.com"}
send
end tell
end tell
EOF
```
**Options:**
- `visible:true` - Shows the compose window before sending (useful for review)
- `visible:false` - Sends silently in the background
### 5. Reply to an Email
Reply to an existing email (preserves threading):
```applescript
osascript <<'EOF'
tell application "Mail"
set targetAccount to account "email@example.com"
set allMailboxes to every mailbox of targetAccount
repeat with mbox in allMailboxes
if name of mbox is "INBOX" or name of mbox is "Inbox" then
-- Find the message to reply to (e.g., by sender)
set foundMessages to (messages of mbox whose sender contains "sender@example.com")
set originalMsg to item 1 of foundMessages
-- Create reply
set theReply to reply originalMsg
tell theReply
set content to "Your reply message here"
send
end tell
return "Reply sent successfully"
end if
end repeat
end tell
EOF
```
**Key points:**
- Use `reply originalMsg` to create a threaded reply (NOT `make new outgoing message`)
- The `reply` command automatically sets the recipient and subject with "Re:"
- Don't use `with opening window false` parameter, it causes syntax errors
- Set the content of the reply before sending
**Reply vs New Email:**
- ❌ **WRONG:** Creating new message to same recipient (breaks threading)
```applescript
set newMessage to make new outgoing message with properties {subject:"Re: Subject"}
```
- ✅ **CORRECT:** Using reply command on original message (maintains threading)
```applescript
set theReply to reply originalMsg
```
### 6. Search Emails by Subject
Find emails matching a subject keyword:
```applescript
osascript <<'EOF'
tell application "Mail"
set targetAccount to account "email@example.com"
set allMailboxes to every mailbox of targetAccount
repeat with mbox in allMailboxes
if name of mbox is "INBOX" or name of mbox is "Inbox" then
set foundMessages to (messages of mbox whose subject contains "keyword")
set output to ""
repeat with msg in foundMessages
set output to output & "Subject: " & subject of msg & return
set output to output & "From: " & sender of msg & return
set output to output & "Date: " & (date received of msg as string) & return
set output to output & "---" & return
end repeat
return output
end if
end repeat
end tell
EOF
```
### 7. Search Emails by Sender
Find all emails from a specific sender:
```applescript
osascript <<'EOF'
tell application "Mail"
set targetAccount to account "email@example.com"
set allMailboxes to every mailbox of targetAccount
repeat with mbox in allMailboxes
if name of mbox is "INBOX" or name of mbox is "Inbox" then
set foundMessages to (messages of mbox whose sender contains "sender@example.com")
set output to "Found " & (count of foundMessages) & " messages" & return & return
repeat with msg in foundMessages
set output to output & subject of msg & return
end repeat
return output
end if
end repeat
end tell
EOF
```
### 8. Get Email Metadata Without Content
Get subject, sender, and date without loading full content (faster):
```applescript
osascript <<'EOF'
tell application "Mail"
set targetAccount to account "email@example.com"
set allMailboxes to every mailbox of targetAccount
repeat with mbox in allMailboxes
if name of mbox is "INBOX" or name of mbox is "Inbox" then
set recentMsgs to items 1 thru 10 of messages of mbox
set output to ""
repeat with msg in recentMsgs
set output to output & subject of msg & " | " & sender of msg & return
end repeat
return output
end if
end repeat
end tell
EOF
```
### 9. Check Unread Message Count
Count unread messages in inbox:
```applescript
osascript <<'EOF'
tell application "Mail"
set targetAccount to account "email@example.com"
set allMailboxes to every mailbox of targetAccount
repeat with mbox in allMailboxes
if name of mbox is "INBOX" or name of mbox is "Inbox" then
set unreadCount to count of (messages of mbox whose read status is false)
return "Unread messages: " & unreadCount
end if
end repeat
end tell
EOF
```
### 10. Move Email to Mailbox
Move a message to a different mailbox:
```applescript
osascript <<'EOF'
tell application "Mail"
set targetAccount to account "email@example.com"
set allMailboxes to every mailbox of targetAccount
-- Find the source mailbox
repeat with mbox in allMailboxes
if name of mbox is "INBOX" then
set theMessage to item 1 of messages of mbox
-- Find the destination mailbox
repeat with destBox in allMailboxes
if name of destBox is "Archive" then
move theMessage to destBox
return "Message moved to Archive"
end if
end repeat
end if
end repeat
end tell
EOF
```
### 11. Delete Emails by Criteria
Delete emails matching specific criteria:
```applescript
osascript <<'EOF'
tell application "Mail"
set targetAccount to account "email@example.com"
set allMailboxes to every mailbox of targetAccount
repeat with mbox in allMailboxes
if name of mbox is "INBOX" then
set messagesToDelete to (messages of mbox whose subject contains "spam")
repeat with msg in messagesToDelete
delete msg
end repeat
return "Deleted " & (count of messagesToDelete) & " messages"
end if
end repeat
end tell
EOF
```
## Common Mailbox Names
Different email providers use different mailbox names:
### Gmail Accounts
- `INBOX` - Main inbox
- `[Gmail]/All Mail` - All mail archive
- `[Gmail]/Sent Mail` - Sent messages
- `[Gmail]/Trash` - Deleted items
- `[Gmail]/Drafts` - Draft messages
- `[Gmail]/Spam` - Spam folder
### iCloud Accounts
- `Inbox` - Main inbox (note the capitalisation)
- `Sent Messages` - Sent mail
- `Trash` - Deleted items
- `Drafts` - Draft messages
### Other Providers
- May use `Sent Items`, `Deleted Items`, etc.
- Always iterate through mailboxes and check names
## Email Message Properties
Common properties you can access on a message object:
```applescript
subject of msg -- Email subject line
sender of msg -- Sender email address
date received of msg -- Date the email was received
date sent of msg -- Date the email was sent
content of msg -- Full email body (can be slow)
read status of msg -- Boolean: true if read, false if unread
flagged status of msg -- Boolean: true if flagged/starred
message id of msg -- Unique message identifier
to recipients of msg -- List of recipient objects
cc recipients of msg -- List of CC recipient objects
all headers of msg -- Raw email headers
message size of msg -- Size in bytes
```
## Error Handling
### Common Errors and Solutions
**Error: "Can't get inbox of account"**
```applescript
-- ❌ WRONG: Trying to access inbox directly
tell application "Mail"
set targetAccount to account "email@example.com"
set inboxMsgs to messages of inbox of targetAccount -- This fails!
end tell
-- ✅ CORRECT: Iterate through mailboxes
tell application "Mail"
set targetAccount to account "email@example.com"
set allMailboxes to every mailbox of targetAccount
repeat with mbox in allMailboxes
if name of mbox is "INBOX" or name of mbox is "Inbox" then
set inboxMsgs to messages of mbox
end if
end repeat
end tell
```
**Error: "Can't get address of account"**
```applescript
-- ❌ WRONG: address property is unreliable
if address of acc contains "email@example.com" then
-- ✅ CORRECT: Use name property instead
if name of acc contains "email@example.com" then
```
**Error: "Can't get item 1 of every account"**
```applescript
-- ❌ WRONG: Don't try to access properties in bulk operations
repeat with acc in accounts
if address of acc contains "..." then -- This fails!
-- ✅ CORRECT: Get properties individually
repeat with acc in accounts
set accName to name of acc
if accName contains "..." then
```
**Error: Message not found or mailbox doesn't exist**
```applescript
-- Solution: Always check existence first
set allMailboxes to every mailbox of targetAccount
if (count of allMailboxes) = 0 then
return "No mailboxes found for this account"
end if
```
## Best Practices
1. **Always list accounts first** when debugging:
```bash
osascript -e 'tell application "Mail" to name of every account'
```
2. **Check mailbox names** before accessing:
```applescript
set mailboxNames to name of every mailbox of targetAccount
```
3. **Use heredoc syntax** for multi-line AppleScript in bash:
```bash
osascript <<'EOF'
tell application "Mail"
-- Your script here
end tell
EOF
```
4. **Handle case sensitivity** in mailbox names:
```applescript
if name of mbox is "INBOX" or name of mbox is "Inbox" then
```
5. **Limit message retrieval** to avoid slowdowns:
```applescript
set recentMsgs to items 1 thru 10 of messages of mbox
```
6. **Check message count** before iterating:
```applescript
set msgCount to count of messages of mbox
if msgCount < numToFetch then set numToFetch to msgCount
```
7. **Use `return` early** when you find what you need:
```applescript
repeat with mbox in allMailboxes
if name of mbox is "INBOX" then
-- Process and return
return result
end if
end repeat
```
## Performance Tips
1. **Don't load content unnecessarily** - Getting `content of msg` is slow
2. **Limit the number of messages** processed in one script
3. **Use filters** (`whose` clauses) to narrow results before processing
4. **Cache mailbox references** if doing multiple operations
## Security and Privacy Considerations
1. **Mail access requires permissions** - macOS will prompt for access on first use
2. **Be careful with automation** - Test sending scripts with visible:true first
3. **Respect user privacy** - Don't log sensitive email content
4. **Use specific searches** - Avoid processing entire mailboxes when possible
## Quick Reference Commands
```bash
# List all accounts
osascript -e 'tell application "Mail" to name of every account'
# Get inbox message count for an account
osascript <<'EOF'
tell application "Mail"
set targetAccount to account "email@example.com"
repeat with mbox in mailboxes of targetAccount
if name of mbox is "INBOX" or name of mbox is "Inbox" then
return count of messages of mbox
end if
end repeat
end tell
EOF
# Get unread count
osascript <<'EOF'
tell application "Mail"
set targetAccount to account "email@example.com"
repeat with mbox in mailboxes of targetAccount
if name of mbox is "INBOX" then
return count of (messages of mbox whose read status is false)
end if
end repeat
end tell
EOF
# List all mailbox names for an account
osascript <<'EOF'
tell application "Mail"
set targetAccount to account "email@example.com"
set mailboxNames to name of every mailbox of targetAccount
return mailboxNames as string
end tell
EOF
```
## When to Use This Skill
Invoke this skill when you need to:
- Read emails from Apple Mail
- Send automated emails
- Reply to emails (maintaining thread context)
- Search for specific emails
- Manage mailboxes programmatically
- Count unread messages
- Move or delete emails based on criteria
- Extract email metadata
- Automate email workflows
## Integration with Other Workflows
When working with email automation:
1. **Email notifications** - Send alerts when specific events occur
2. **Data extraction** - Parse emails for specific information
3. **Email filtering** - Auto-file or delete emails based on rules
4. **Reporting** - Generate summaries of email activity
5. **Backup** - Export email data for archival
## Lessons Learned (Trial and Error)
The key insights from developing this skill:
1. **Don't use `inbox of account` directly** - Always iterate through mailboxes
2. **Account properties vary** - Use `name` not `address`
3. **Mailbox names vary by provider** - Check for both "INBOX" and "Inbox"
4. **Error -1728 usually means property doesn't exist** - Try a different property
5. **Bulk operations on `every X` can fail** - Get properties individually
6. **Use `items 1 thru N`** for safe list slicing with bounds checking
7. **Use `reply` command, not new messages** - To maintain threading, use `reply originalMsg` instead of creating a new outgoing message
8. **Don't use `with opening window` parameter** - The `reply` command doesn't support the `with opening window false` parameter, causes syntax errors
Remember: AppleScript error messages are often cryptic. When debugging, simplify the script to the minimum necessary and build up complexity gradually.