outlook-email-scan

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