SmartMail

SmartMail is a Flask web application that connects a mailbox (Outlook via Microsoft Graph, and Gmail) to an AI-assisted triage and drafting workflow: it syncs mail, stores it in MongoDB/Postgres, and uses OpenAI to classify, summarise, extract data from, and draft replies to messages.

See also

• Architecture — runtime boot sequence, auth flow, background sync, AI pipeline, deployment
• Database — SQLite and MongoDB schema/collections
• API Reference — HTTP routes actually reachable, and dead/unregistered ones to avoid relying on
• User Guide — what an end user actually sees and does
• Workflow — local dev setup, running locally, building the exe/service
• CLI Quick Reference — python -m app.main commands
• Changelog

Purpose

• Log into Outlook using Microsoft Graph and MSAL (device-code OAuth flow).
• Sync inbox mail (including threads) into a local store for fast browsing and search.
• Apply GPT-based classification, summarisation, key-value extraction, and reply drafting per message and per thread.
• Provide an admin UI for categories, GPT prompts, people, and mail folders.
• Run as a background Windows service or a double-clickable desktop executable, not just a dev server.

Architecture (summary — see the Architecture page for detail)

• Web app: Flask app defined in app/main.py, served by waitress (see run.py). Routes are split into blueprints under app/routes/ (inbox, compose, categories, category prompts, GPT prompts, people, admin, MongoDB admin, email) — though several of these blueprints are defined but never actually registered; see API Reference for which routes are truly live.
• Auth: app/auth.py (the module actually used at runtime) handles MSAL device-code login and silent token refresh via a token cache at cache.bin (relative to the process's working directory). app/auth_public.py is a second, mostly-unused implementation with a different cache path — see Architecture §4.
• Mail integration: app/graph.py wraps Microsoft Graph calls (list/search messages, drafts, folders, move/mark-read). app/gmail_sync.py covers Gmail. app/attachments.py and app/text_extraction.py handle attachment download and OCR/text extraction (pytesseract, PyMuPDF, python-docx).
• Storage: SQLite (app/database.py, actively used only for metrics/audit logs) and MongoDB (app/database_mongo.py and others — the real store for email content, summaries, categories). See Database for the full inventory and known inconsistencies.
• AI layer: app/gpt.py, app/llm.py, app/summariser.py, app/thread_summarizer.py call OpenAI for summarisation, key-value extraction, and reply drafting. Category classification is keyword-based, not an LLM call — see Database/Architecture.
• Background sync: only app/poller_mongo.py's poller is actually active; several other poller modules in the repo are dead or dormant — see Architecture §3.
• Automation/webhooks: app/automation1.py provisions a Graph webhook route, but no subscription is ever created against Graph, so it never receives real traffic today.
• Packaging: SmartMail.spec / SmartMail_Service.spec are PyInstaller specs for a desktop exe and a Windows service respectively; a third path (run_api.cmd + wsgi.py) also exists. See Workflow.

Configuration

• Environment loaded from env/.env.development (via python-dotenv); includes OPENAI_API_KEY, CLIENT_ID, and mail/DB connection settings.
• config/config.ini + config/load_config.py provide structured configuration beyond plain env vars; scripts/check_config.py validates required keys. config/schema.json is currently empty.
• Azure AD app registration requires delegated permissions: Mail.ReadWrite, Mail.Send, MailboxSettings.ReadWrite, offline_access, User.Read.

Development

See Workflow for the full setup/build/deploy sequence. Quick start:

pip install -r requirements.txt
python -m app.main login          # device-code sign-in
python -m app.main init-db
python -m app.main inbox --top 10

Known direction

• Branch NEW_POPUP (current work) is iterating on app/templates/outlook.html.
• Recent history shows active work on inbox-loading slowness and an editable-draft option, and a send-button fix (see changelog).
• The codebase carries a substantial amount of dead/duplicated code (unregistered blueprints, redundant pollers, two divergent auth implementations) — see Architecture and API Reference for specifics before extending those areas.