Apple Mail (Read Only)

Read email via Mail.app AppleScript. No sending or modifying emails.

Prerequisites

• Mail.app running and logged in
• Automation permissions granted (System Settings → Privacy & Security → Automation → Terminal/Claude Code → Mail)
• If first access attempt times out, ask user to check for macOS permission dialog

Reliability: always wrap osascript with timeout + retry

Apple Mail's AppleScript bridge hangs intermittently — sometimes for minutes — even on simple queries. The AppleScript-internal with timeout of N seconds does NOT kill a wedged osascript process. Always wrap calls with shell-level timeout and retry on failure.

Pattern:

# Run osascript with 15s shell timeout, retry up to 3 times with 2s backoff.
mail_query() {