SmartMail User Guide

Two separate logins — don't confuse them

1. SmartMail app login (/login) — a plain username/password form (no Microsoft branding). Credentials are hardcoded in app/main.py as a fixed two-account list (admin and operator roles); they are not read from the database. This login gate is only actually enforced on /logout and the GPT Prompt admin endpoints — most pages and API routes, including the Outlook inbox and most of the admin dashboard, currently work without ever logging in through this form. role_required exists in the code but isn't wired to any route, so the admin/operator/viewer distinction has no effect on what you can do today.
2. Microsoft 365 mailbox sign-in — unrelated to the form above; this is what lets SmartMail read/send mail via Microsoft Graph. It's a one-time setup step, not a browser button: run python -m app.main login (or SmartMail.exe login), which opens a device-code/interactive Microsoft sign-in flow. Once complete, a token cache file lets the server refresh silently. Without this, mail-related screens will show "Not authenticated" and API calls return 401.

/api/auth-status reflects only the Microsoft 365 token state, not the app login.

The Outlook inbox (/outlook)

A three-pane mail client: Folders | Message list | Reader.

Top bar — search box (filters the loaded list by subject/sender/preview, or re-queries Mongo by category if any categories are selected), Compose button, and a Dark/Light theme toggle.

Folders pane — real Outlook folders (Inbox, Drafts, Sent Items, Deleted Items, Junk, Archive, …) with unread-highlighted item-count badges. A category filter dropdown lets you multi-select categories to narrow the list. A Project section is a purely personal, browser-local (localStorage) organizing tree — not synced to Graph or Mongo — for tagging messages informally.

Message list — shows the current folder, with a count selector (20/50/100/200/All). Conversations expand inline (twist-arrow) to show grouped thread messages. Right-click a message for: Copy Message/Thread ID, Delete, Archive, Pin, Categorize (live category submenu), "Move to project", and Reply/Reply-all/Forward shortcuts (hidden in Drafts).

Reader pane — opening any message automatically triggers a background AI summary (per-email and rolling per-thread) with no button to click — this is how summaries populate the admin Database tab. Action bar: Reply/Reply-all/Forward (replaced by Send when viewing a Drafts item), Archive, Delete, and a Category pill. Below the body, an "Input Text" / Generate box (Inbox only) lets you type free-form instructions for an AI-drafted reply (POST /api/draft/generate). Generated/reply/forward drafts open in an AI Reply Preview dialog with Copy, Regenerate, Save draft, Send (with confirmation), and Close. A fixed company signature is auto-appended to generated replies/forwards.

Opening a message from Drafts makes the reader body directly editable, with a single Send button replacing the usual action bar.

Composing new mail

The Compose button opens a To/Subject/Body dialog with To-field autocomplete (Microsoft Graph People/Contacts search, min 2 characters). Note: CC/BCC fields aren't present in the Compose dialog today, and the underlying /api/compose/send endpoint currently has a bug that will error on any real send — see API Reference. Reply/Reply-all/Forward/Generate use the separate, working draft pipeline (/api/draft/generate → /api/draft/update → /api/draft/send) instead.

Admin dashboard (/admin)

A sidebar with tabs:

• Dashboard — embeds the Outlook inbox (/outlook) in an iframe; same interface as above.
• Database (Email Management → Database) — searchable/paginated cards over the stored email_summaries records (search, direction filter, category filter). Each card supports Edit (category, "should generate draft" flag, and text fields) and Delete.
• GPT Prompt (Email Management → GPT Prompt) — manage reusable named prompts and category-specific reply-drafting templates. This is the one tab where the app login is actually enforced — you'll get a 401 here if you haven't logged in via /login.
• Category (Email Management → Category) — manage categories: name, description, and a free-text "Prompt rules" field (this is keyword-matching classification logic, not an AI prompt — see Database). Deleting a category resets its emails to "unknown"; adding or editing a category's rules immediately re-tags recent mail.
• Other admin options — currently placeholder text only (Health/status checks, IMAP/webhook configuration, manual resync) with no working controls yet.
• Users (Admin → Users) — create/list admin user records. Note: creating a user here does not grant them a way to log in via /login — that form checks its own hardcoded two-account list, unrelated to this table. Don't rely on this tab for access control yet.
• Logout — clears your app-login session.

Other pages you might stumble on

• /inbox, /folder/<name> — an older, plain server-rendered table view predating the Outlook-style client. Still reachable by direct URL but not linked from navigation; avoid using this without an authenticated Microsoft 365 token, since it will crash the server process rather than 401 (see API Reference).
• /dashboard — a metrics dashboard (throughput/errors/GPT spend) backed by the SQL audit-log store.
• /trace/<trace_id> — shows the ordered processing steps recorded for a given trace id.

Troubleshooting

• "Not authenticated" / 401 on mail screens → run python -m app.main login again; delete cache.bin first if it seems stuck.
• GPT Prompt tab returns 401 → you need to log in via /login first (this is the one enforced tab).
• A category's mail count looks stale right after editing → recategorisation runs automatically on add/edit/delete, but only over the most recent ~800 summaries.