| name | outlook-email-scan |
| description | Scan Outlook desktop emails via macOS Accessibility API, save as markdown and JSON, and summarize. Supports search, multi-account, multi-folder, date/sender filtering. Use when user asks to "read my emails", "check my inbox", "scan outlook", "search my emails", "what emails do I have", or "check my outlook". |
| version | 2.0.0 |
/outlook-email-scan -- Scan Outlook Desktop Emails
Scan Outlook accounts via macOS Accessibility API, save new emails as markdown (and JSON for Pro), and provide a summary. Supports keyword search, multi-folder scanning, date/sender filtering. No admin permissions, no OAuth, no API keys required.
Protocol
Step 0: Check Dependencies
Before scanning, verify the repo is cloned and dependencies are installed. Run this once -- it's a no-op if already installed.
if [ ! -d "$HOME/Documents/outlook-email-scanner" ]; then
cd ~/Documents && git clone https://gitlab.com/timo2026/outlook-email-scanner.git
fi
cd ~/Documents/outlook-email-scanner && pip install -e . -q
Step 1: Determine Scan Type
Ask the user what they need, or infer from context:
| User intent | Scan type |
|---|
| "check my inbox" / "read my emails" | Basic scan: scan_outlook() |
| "search for [keyword]" | Search scan: scan_outlook(search_query="keyword") |
| "check all accounts" | Multi-account: scan_all_outlook_accounts() |
| "check my sent items" | Folder scan: scan_outlook(folders=["Sent Items"]) |
| "what accounts do I have" | Discovery: discover_accounts() |
Step 2: Run the Scan
Important: Outlook must be open and showing the inbox before scanning.
Basic scan (free tier -- up to 30 emails)
import sys
sys.path.insert(0, str(__import__('pathlib').Path.home() / 'Documents' / 'outlook-email-scanner'))
from src.scanner import scan_outlook
stats = scan_outlook()
Search scan (Pro)
stats = scan_outlook(search_query="quarterly report")
Multi-account auto-discovery (Pro)
from src.scanner import scan_all_outlook_accounts
results = scan_all_outlook_accounts()
Multi-folder scan (Pro)
stats = scan_outlook(
account="work",
folders=["Inbox", "Sent Items", "Drafts"],
)
Discover accounts (no scan)
from src.scanner import discover_accounts
accounts = discover_accounts()
Step 3: Read Scanned Emails
After scanning, read the saved markdown files from the output directory:
~/Desktop/outlook-emails/<account>/*.md
Read the most recent files (sorted by modification time) and present a summary to the user.
For Pro users, JSON files are also available at the same path with .json extension for structured access.
Step 4: Present Results
Summarize what was scanned:
Scanned [account]: [processed] new emails found, [skipped] duplicates skipped.
Recent emails:
1. **[Subject]** from [Sender] ([Date]) -- [first line of body]
2. ...
Step 5: Offer Follow-up
Ask the user what they'd like to do:
- Reply to any email? (draft a response)
- Search for something specific?
- Scan a different account or folder?
- Summarize a specific email in detail?
Troubleshooting
| Issue | Fix |
|---|
| "Outlook not found" | Make sure Outlook is running and showing inbox |
| "Accessibility permission denied" | System Settings > Privacy & Security > Accessibility > add your terminal |
| Empty scan results | Ensure the reading pane is visible (not collapsed) |
| "No accounts found" | Expand the sidebar in Outlook so account list is visible |
