Scan Inbox

Scan Inbox

Analyzes your Apple Mail inbox to identify unread, actionable, and priority messages within a specified time range.

When to Use This Skill

Activate this skill when the user asks questions like:

• "Check my email"
• "What unread emails do I have?"
• "Any urgent emails?"
• "Show me actionable items from my inbox"
• "Triage my email from today"

What This Skill Does

1. Scans all inbox accounts in Apple Mail
2. Filters messages by time range (default: last 24 hours)
3. Identifies unread messages
4. Detects actionable keywords (deadline, urgent, action required, meeting, request, etc.)
5. Identifies priority/flagged messages
6. Returns structured data with counts and message details

Instructions

Step 1: Determine Time Range

Ask the user if they want a specific time range, or use these defaults:

• "Today" or "recent" → 24 hours
• "This week" or "recent days" → 48-72 hours
• Specific request → Honor their time range

Step 2: Execute the Scan

Run the AppleScript skill using the Bash tool:

\\\bash osascript .claude/skills/scan-inbox/scripts/scan_inbox.scpt false \\\

Parameters:

• ``: Number of hours to look back (e.g., 24, 48, 72)
• false: Set to true for priority-only mode

Step 3: Parse Results

The script returns:

• success: boolean (true/false)
• unreadCount: Total unread messages
• actionableCount: Messages with actionable keywords
• priorityCount: Flagged/priority messages
• unreadList: Array of unread message details (sender, subject, date, flagged status)
• actionableList: Array of actionable messages
• priorityList: Array of priority messages

Step 4: Present Results to User

Format the output in a clear, actionable way:

Example Response: \\\` 📬 Inbox Summary (Last 24 Hours)

📊 Overview:

• 38 unread messages
• 0 actionable items
• 0 priority/flagged

📧 Recent Unread:

1. Google - Security alert
2. C# Digest - Newsletter
3. BAC Credomatic - Transaction notification

... (showing top 5-10)

💡 Next Steps:

• No urgent items requiring immediate attention
• Review newsletters when you have time

\\\`

Step 5: Offer Follow-up Actions

Ask if the user wants to:

• See more details about specific emails
• Flag or organize certain messages
• Extract tasks from actionable emails
• Check a different time range

Actionable Keywords Detected

The skill identifies these keywords in email subjects:

• deadline
• urgent
• action required
• meeting
• request
• please review
• asap
• todo
• action item

Error Handling

If the script fails:

1. Check Mail automation permissions: System Settings → Privacy & Security → Automation → Terminal/Claude
2. Verify Apple Mail is running
3. Try with a smaller time range if timeout occurs

Example Usage

User: "Check my email from today"

Claude Response: \\\bash osascript .claude/skills/scan-inbox/scripts/scan_inbox.scpt 24 false \\\

Then format and present the results to the user.

Supporting Files

For advanced usage and detailed documentation, see [reference.md](reference.md).

For examples of common use cases, see [examples.md](examples.md).

Performance

• Typical execution: ~2 seconds
• Max timeout: 30 seconds
• Works with multiple Mail accounts

Privacy Note

This skill only reads mail metadata (sender, subject, date, flags). It does not access email body content to protect privacy.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ronnycoding
• Source: ronnycoding/my-personal-assistant
• License: MIT

Install and usage instructions live in the source repository linked above.