Email Notifications

Email Notifications via Apple Mail

Set up real-time email notifications: when the agent’s iCloud email receives a message from a known contact, Apple Mail triggers an AppleScript that notifies the OpenClaw agent.

Overview

Known contact sends email
         │
         ▼
   Apple Mail.app
   (Mail Rule fires)
         │
         ▼
  NotifyAgent.applescript
         │
         ▼
  openclaw agent --agent main-agent
  --message "New email from known contact. ID: <id>"
         │
         ▼
  Agent fetches email details
  via mail-read, triages it

Two mechanisms trigger email processing:

1. Real-time notifications — A Mail.app rule fires an AppleScript when an email arrives from a known contact
2. Periodic heartbeat checks — The agent’s heartbeat routine checks the inbox 2-3x/day for anything the rule didn’t catch

Prerequisites

• macOS with Apple Mail configured for the agent’s iCloud email
• OpenClaw installed and running
• The main agent has exec access (needed to process emails)

Setup Steps

1. Configure Apple Mail

1. Open Mail.app on the agent Mac
2. Add the agent’s iCloud account if not already set up
3. Verify mail is syncing (send a test email)

2. Create the Notification Script

Create NotifyAgent.applescript:

-- Triggered by Mail.app rule when sender is in Contacts
-- Only passes the numeric message ID (avoids command injection)

using terms from application "Mail"
    on perform mail action with messages theMessages for rule theRule
        repeat with theMessage in theMessages
            set theId to id of theMessage

            -- Export PATH (Mail.app sandbox has minimal PATH)
            -- Run in background (&) so Mail rule doesn't block
            set theCommand to "export PATH=/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin; openclaw agent --agent main-agent --message 'New email from known contact. ID: " & theId & "' > /dev/null 2>&1 &"

            do shell script theCommand
        end repeat
    end perform mail action with messages
end using terms from

Security notes:

• Only the numeric message ID is passed, not sender or subject (prevents command injection from crafted email headers)
• The agent retrieves email details safely through its own tools
• PATH export is required because Mail.app’s sandbox only has /usr/bin:/bin
• Background execution (&) prevents the Mail rule from blocking

3. Compile and Deploy

osacompile -o ~/Library/Application\ Scripts/com.apple.mail/NotifyAgent.scpt \
  /path/to/NotifyAgent.applescript

4. Create the Mail Rule

1. Mail.app > Settings > Rules > Add Rule
2. Description: “Notify Agent (known contacts)”
3. If: Sender is in my Contacts
4. Action: Run AppleScript > NotifyAgent.scpt

5. Verify

Send a test email from a contact in the agent Mac’s address book:

openclaw logs --follow

You should see the agent receive: New email from known contact. ID: 12345

How It Works

The AppleScript

The script is intentionally minimal for security:

• PATH export is required — Mail.app is sandboxed and do shell script only has /usr/bin:/bin:/usr/sbin:/sbin in PATH
• Only the numeric ID is passed — avoids command injection from crafted email headers
• Background execution — the & and /dev/null redirect prevent the Mail rule from blocking

Heartbeat Checks

The agent’s HEARTBEAT.md should include an inbox check task:

- [ ] Check inbox (2-3x/day): review unread emails, flag important ones for owner

This covers emails from unknown senders or cases where the Mail rule didn’t fire (e.g., Mail.app was not running).

Email Processing Workflow

Once notified, the agent follows a zero-inbox approach:

1. Authenticate — mail-auth-check <id> (blocking, must pass before acting). See Email Authentication.
2. Read the email — mail-read <id>
3. Mark read — mail-mark-read <id>
4. Archive when processed — mail-archive <id>
5. Delete if not needed — via Mail.app directly

Goal: empty inbox at all times. Process immediately, archive when done. Flag important items for the owner via iMessage.

Troubleshooting

AppleScript not firing

• Verify the rule is enabled in Mail -> Settings -> Rules
• Check that the sender is in Contacts on the agent Mac (not just on iCloud — Contacts must be synced)
• Test the script manually: osascript ~/Library/Application\ Scripts/com.apple.mail/NotifyAgent.scpt

”env: node: No such file or directory”

• Mail.app’s sandbox gives do shell script a minimal PATH (/usr/bin:/bin:/usr/sbin:/sbin)
• The script must explicitly export PATH to include /opt/homebrew/bin where node lives

”Permission denied” from AppleScript

• Mail.app needs Automation permission to run scripts
• System Settings -> Privacy & Security -> Automation -> Mail -> allow

Agent doesn’t respond

• Verify OpenClaw is running: openclaw status
• Check that the main agent has auth configured
• Check logs: openclaw logs --follow

Re-deploying after script changes

After editing the AppleScript source, recompile:

osacompile -o ~/Library/Application\ Scripts/com.apple.mail/NotifyAgent.scpt \
  /path/to/NotifyAgent.applescript

No need to recreate the Mail rule — it references the compiled .scpt by path.