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.

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

• 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).
• Auth: app/auth.py / app/auth_public.py handle MSAL device-code login and silent token refresh; a persistent token cache (token_cache.bin) avoids repeated interactive logins.
• 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: app/database.py (SQLAlchemy, relational: metrics/audit log) and app/database_mongo.py / app/mongo_client.py / app/mongo_emails.py (MongoDB: email content, summaries, categories). smartmail.db is the local SQLite/relational file referenced at the repo root.
• AI layer: app/gpt.py, app/llm.py, app/summariser.py, app/thread_summarizer.py call OpenAI for gpt-classify, gpt-summarise, gpt-extract, and gpt-draft operations, both via CLI (app/main.py commands) and via the web routes.
• Background sync: app/poller.py / app/poller_mongo.py / app/background_inbox_sync.py / app/services/inbox_sync.py poll the mailbox and keep MongoDB summaries current without requiring a user to open each message first. Started from app.main at app boot (start_background_summary_poller).
• Automation/webhooks: app/automation1.py (poll_inbox, run_polling_loop, handle_webhook_notification) exposes a Graph subscription/webhook path in addition to polling.
• Packaging: SmartMail.spec / SmartMail_Service.spec are PyInstaller specs. run.py is the desktop-exe entry point (opens a browser to /outlook after starting the server on port 5001). service_wrapper.py (win32serviceutil) runs the same Flask app as a Windows service.

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/schema.json + config/load_config.py provide structured configuration beyond plain env vars; scripts/check_config.py validates it.
• Azure AD app registration requires delegated permissions: Mail.ReadWrite, Mail.Send, MailboxSettings.ReadWrite, offline_access, User.Read.

Development

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

Run the full web app directly with python run.py, or via python -m app.main for the CLI surface (see quick-reference once added).

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).