Read email via Apple Mail.app and AppleScript. Use when asked to check, search, or read emails. READ ONLY — no sending or modifying emails.
Read email via Mail.app AppleScript. No sending or modifying emails.
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() {
local script="$1" attempt
for attempt in 1 2 3; do
result=$(timeout 15 osascript -e "$script" 2>&1) && { echo "$result"; return 0; }
sleep 2
done
echo "ERROR: Mail query failed after 3 attempts" >&2
return 1
}
# Usage:
mail_query 'tell application "Mail" to count (messages of inbox whose read status is false)'
Reasonable defaults: 15s timeout, 3 retries, 2s sleep. Bump the timeout for messages of every mailbox (cross-account searches) to 60s. If all 3 retries fail, report the failure and move on — never block a briefing on Mail.
See docs/email-accounts.md for which accounts are configured on which machines.
osascript -e 'tell application "Mail" to get name of every account'
osascript -e 'tell application "Mail" to count (messages of inbox whose read status is false)'
osascript -e 'tell application "Mail"
set recentMsgs to messages 1 thru 10 of inbox
repeat with msg in recentMsgs
set msgInfo to "From: " & (sender of msg) & " | Subject: " & (subject of msg) & " | Date: " & (date sent of msg)
log msgInfo
end repeat
end tell'
osascript -e 'tell application "Mail"
set msg to message 1 of inbox
return "From: " & (sender of msg) & "\nSubject: " & (subject of msg) & "\nDate: " & (date sent of msg) & "\n\n" & (content of msg)
end tell'
osascript -e 'tell application "Mail"
set foundMsgs to (messages of inbox whose subject contains "keyword")
count foundMsgs
end tell'
osascript -e 'tell application "Mail"
set foundMsgs to (messages of inbox whose subject contains "keyword")
if (count foundMsgs) > 0 then
set msg to item 1 of foundMsgs
return "From: " & (sender of msg) & "\nSubject: " & (subject of msg) & "\nDate: " & (date sent of msg) & "\n\n" & (content of msg)
else
return "No messages found"
end if
end tell'
osascript -e 'tell application "Mail"
set foundMsgs to (messages of every mailbox of every account whose subject contains "keyword")
-- Note: this can be slow across many accounts
end tell'
osascript -e 'tell application "Mail" to get name of every mailbox of account "Gmail"'
messages of inbox returns a unified inbox across all accountscontent of msg returns plain text body; source of msg returns raw MIMEwhose clauses to filterwith timeout of 60 seconds for slow queriesIf you encounter an AppleScript pattern that fails, a macOS behavior change, or missing guidance in this skill, don't just work around it — fix the skill:
https://github.com/eins78/agent-skills on a new branch, fixing the issue directlyhttps://github.com/eins78/agent-skills with: what failed, the actual behavior, and the suggested fixNever silently work around a skill gap. The fix benefits all future sessions.