FlagFlow

A streamlined workflow for reviewing and processing flagged emails in Microsoft Outlook. Triage your flagged emails in a browser-based dashboard, then batch-execute actions like unflagging or creating reply drafts.

Demo

Try the dashboard without connecting to Outlook:

.\showdemo

This opens the dashboard with sample demo emails. You can explore all features without touching real emails.

Prerequisites

• Windows with Microsoft Outlook desktop app installed and configured
• Python 3.x with pywin32 and Flask: pip install pywin32 flask
• Chrome or Edge browser

Setup

Step 1: Create the Outlook Search Folder

FlagFlow reads from a search folder that contains your flagged emails. You need to create this folder in Outlook Desktop:

1. Open Outlook Desktop (the installed app, not Outlook on the web)
2. In the left sidebar, scroll down to find Search Folders under your mailbox
   • If you don't see it, click the arrow next to your mailbox name to expand it
3. Right-click on Search Folders → select New Search Folder...
4. In the dialog that appears:
   • Scroll down to the Mail section
   • Select "Flagged mail" (or "Mail flagged for follow up")
   • Click OK
5. A new folder called "For Follow Up" (or similar) should appear under Search Folders

Important: FlagFlow looks for folders named For Follow Up, Flagged Mail, or FlaggedEmail. The default name Outlook creates should work automatically.

Step 2: Clone and Install

git clone https://github.com/bkrishnamachari/flagflow.git
cd flagflow
pip install pywin32 flask

Step 3: Verify Setup

1. Make sure you have some flagged emails in Outlook (flag a few test emails if needed)
2. Make sure Outlook Desktop is running
3. Run FlagFlow:

.\flagflow

If everything is set up correctly, you'll see your flagged emails in the dashboard.

Usage

# Start FlagFlow
.\flagflow

# In the dashboard:
# 1. Click action buttons for each email (DEFER/UNFLAG/RESPOND/PRIORITY)
# 2. Add notes for emails you need to respond to
# 3. Click "Execute" to process all actions
# 4. Confirm each batch: Go / Skip / Quit

# Press Ctrl+C in terminal to stop the server when done

Commands

Command	Description
.\flagflow	Fetches flagged emails, starts server, opens dashboard
.\showdemo	Opens dashboard with fake demo emails (no Outlook access)

Action Buttons

Button	Color	What Happens
DEFER	Yellow	No action - email stays flagged for later
UNFLAG	Gray	Clears the flag in Outlook
RESPOND	Purple	Creates a reply draft in your Outlook Drafts folder
PRIORITY	Red	Marked as HIGH_PRIORITY for immediate attention

Dashboard Features

• Auto-load: Opens with today's emails automatically
• One-click actions: Fast button-based action assignment
• Execute in browser: Process all actions with the Execute button
• Batch confirmations: Go / Skip / Quit for each batch
• Sort by Priority: See HIGH_PRIORITY and RESPOND items first
• Search & Filter: Find emails by sender, subject, or body text

How It Works

.\flagflow
   │
   ├─► Fetches flagged emails from Outlook
   ├─► Starts Flask server at localhost:5000
   └─► Opens dashboard in browser

[You triage emails in the dashboard]
   │
   └─► Click "Execute" button
       ├─► UNFLAG actions: Clears flags in Outlook
       ├─► RESPOND actions: Creates reply drafts with your notes
       └─► All done in browser!

Safety Features

• Read-only export: Fetching never modifies your emails
• No deletions: Only clears flags, never deletes emails
• Batch confirmations: Confirm each batch before execution
• Drafts not sent: Reply drafts are saved to Drafts folder, never auto-sent
• Duplicate prevention: Won't process the same action twice
• Audit log: Every action recorded with timestamp

Advanced Usage

# Fetch with options
python fetch_flagged_emails.py --limit 10              # Test with 10 emails
python fetch_flagged_emails.py --max-body-chars 2000   # Limit body size

# Execute with options
python execute_actions.py --dry-run           # Preview only
python execute_actions.py --batch-size 10     # Smaller batches
python execute_actions.py --auto              # Skip confirmations (careful!)

Troubleshooting

"Could not find FlaggedEmail search folder"

• Make sure you created the search folder in Outlook (see Step 1 above)
• Make sure Outlook Desktop is running when you run .\flagflow
• Check that the search folder appears under "Search Folders" in Outlook's sidebar

No emails showing in dashboard

• Verify you have flagged emails in Outlook
• Check that your flagged emails appear in the "For Follow Up" search folder in Outlook
• Try clicking Send/Receive in Outlook to sync, then run .\flagflow again

Emails showing that are already unflagged

• Outlook's search folder can be cached. The tool filters by actual flag status.
• Try Send/Receive in Outlook to force sync, then run .\flagflow again

License

Polyform Noncommercial License 1.0.0

Free for personal, educational, and non-commercial use. See LICENSE for details.