Claude Code Plugins

Community-maintained marketplace

Feedback

apple-mail

@BfdCampos/dotfiles
0
0

Comprehensive guide for accessing and automating Apple Mail using AppleScript, including reading emails, sending messages, and managing mailboxes.

Install Skill

1Download skill
2Enable skills in Claude

Open claude.ai/settings/capabilities and find the "Skills" section

3Upload to Claude

Click "Upload skill" and select the downloaded ZIP file

Note: Please verify skill by going through its instructions before using it.

SKILL.md

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:

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:

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:

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:

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):

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)
set newMessage to make new outgoing message with properties {subject:"Re: Subject"}
  • ✅ CORRECT: Using reply command on original message (maintains threading)
set theReply to reply originalMsg

6. Search Emails by Subject

Find emails matching a subject keyword:

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:

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):

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:

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:

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:

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:

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"

-- ❌ 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"

-- ❌ 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"

-- ❌ 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

-- 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:

    osascript -e 'tell application "Mail" to name of every account'

  2. Check mailbox names before accessing:

    set mailboxNames to name of every mailbox of targetAccount

  3. Use heredoc syntax for multi-line AppleScript in bash:

    osascript <<'EOF'
tell application "Mail"
    -- Your script here
end tell
EOF

  4. Handle case sensitivity in mailbox names:

    if name of mbox is "INBOX" or name of mbox is "Inbox" then

  5. Limit message retrieval to avoid slowdowns:

    set recentMsgs to items 1 thru 10 of messages of mbox

  6. Check message count before iterating:

    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:

    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

# 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.