FinMail Intelligence Dashboard

A local-first, BYOK (Bring Your Own Key) desktop application that monitors your email for financial content and uses Claude AI to generate structured intelligence summaries.

Features

• Unread-Only Processing: Only fetches and analyzes unread emails — no wasted API calls on messages you've already seen
• Email Integration: IMAP support for Gmail, Outlook, and custom servers
• Smart Classification: Keyword matching + LLM classification to detect financial emails
• Attachment Processing: Extracts text from PDF, DOCX, XLSX, CSV, and TXT attachments
• AI-Powered Analysis: Structured summaries with TLDR, key figures, sentiment, action items, risk flags
• Credit Exhaustion Handling: Clear dialog when API credits run out, with a direct link to refill
• Secure by Design: API keys and credentials stored in OS keychain — never in plaintext
• Local-First: SQLite database, zero cloud dependency beyond API calls you authorize
• Dark Mode UI: Modern card-based dashboard with search, filters, and detail views

Quick Start (macOS .app)

Build a double-clickable app bundle — no terminal needed for end users:

cd emailapp
pip install -r requirements.txt
python build_app.py

This creates dist/FinMail.app. Double-click to launch. Distribute this .app to anyone — they don't need Python installed.

Development Setup

Prerequisites

• Python 3.10+ (with Tkinter — the python.org installer includes it)
• A Claude API key from Anthropic Console
• An email account with IMAP enabled (Gmail requires an App Password)

Run from Source

cd emailapp
pip install -r requirements.txt
python main.py

Gmail Setup

1. Enable 2-Factor Authentication on your Google account
2. Generate an App Password: Google Account → Security → App Passwords
3. Use that App Password (not your regular password) in the app's email configuration
4. IMAP server: imap.gmail.com, port: 993

Outlook Setup

1. Use your account password
2. IMAP server: outlook.office365.com, port: 993

Architecture

emailapp/
├── main.py              # Entry point
├── build_app.py         # PyInstaller → .app bundle builder
├── core/
│   ├── config.py        # Configuration management
│   ├── keyring_manager.py  # Secure credential storage (OS keychain)
│   ├── database.py      # SQLite database (thread-safe)
│   ├── email_fetcher.py # IMAP fetching (unread-only + mark-as-seen)
│   ├── text_extractor.py   # PDF, DOCX, XLSX, CSV, TXT extraction
│   └── ai_analyzer.py   # Claude API + credit exhaustion detection
├── gui/
│   ├── app.py           # Main application window + orchestrator
│   ├── components.py    # Cards, badges, search bar, credit dialog
│   ├── sidebar.py       # Navigation sidebar
│   ├── onboarding.py    # 3-step setup wizard
│   ├── dashboard.py     # Email card list view
│   ├── detail_view.py   # Full analysis + attachments
│   └── settings.py      # API key, email, preferences, export
└── requirements.txt

Data Storage

All data is stored locally at ~/.finmail/:

• finmail.db — SQLite database with emails, analyses, and usage stats
• attachments/ — Downloaded email attachments
• config.json — Non-sensitive preferences

Credentials (API key, email password) are stored in your OS keychain via the keyring library.

API Usage & Cost Control

The app uses Claude Sonnet 4 for:

• Classification: ~100 tokens per email (only for emails that don't match keyword filters)
• Analysis: ~500-2000 tokens per email depending on content length

Cost controls:

• Unread-only: Already-read emails are never processed
• Auto-skip large docs: Attachments exceeding the token threshold are skipped in auto mode
• Credit exhaustion dialog: When credits run out, a modal appears with a direct link to refill
• Usage tracking: Real-time stats in the status bar and Settings page