MailMind

MailMind is a privacy-first, multi-account email client powered by a local AI assistant. It prioritizes, organizes, summarizes and drafts email locally while a deterministic policy engine controls every AI action.

MailMind is a native Python desktop application for Windows 10/11. It remains a useful IMAP/SMTP email client when AI is disabled, paused, missing, or temporarily unavailable.

Source edition status: the core desktop experience, isolated demo inbox, account management, secure credentials, IMAP/SMTP engine, local cache, search, local-AI process control, strict AI schemas, permissions, policy decisions, approvals, tasks, rules, audit and undo foundations are implemented. See Limitations for the honest V1 boundary.

Highlights

• Native three-pane desktop interface built with Python and PySide6
• Smooth, meaningful interaction feedback and animated local-AI startup states
• Multiple independent email accounts with a unified inbox
• IMAP synchronization, SMTP sending, local drafts and offline reading
• Credentials stored through Windows Credential Manager—not in SQLite
• Sanitized email HTML and remote images blocked by default
• Per-account AI modes: Off, Observe, Organize and Assist
• Managed llama.cpp runtime with a configurable OpenAI-compatible endpoint
• Strict structured analysis for priority, spam, intent, summaries and deadlines
• Deterministic Policy Engine between every AI proposal and mailbox action
• Approval Center, AI Activity audit trail, and undo for supported local actions
• AI Priority briefing, extracted tasks and source-linked Ask Inbox retrieval
• Deterministic rules previewed before activation
• Realistic demo mode that never shares data paths with live accounts

Screenshots

These are captures of the real PySide6 application running against MailMind's isolated demo data.

Three-pane inbox

Priority briefing

Local AI control

Approval Center

Independent account permissions

Architecture

flowchart LR
    IMAP[IMAP providers] --> Sync[Background sync]
    Sync --> DB[(Local SQLite cache)]
    DB --> UI[PySide6 desktop UI]
    DB --> Retrieval[Local retrieval]
    DB --> AI[Local AI analysis]
    AI --> Proposal[ProposedAction]
    Proposal --> Policy{Deterministic PolicyEngine}
    Policy -->|DENY| Audit[Audit log]
    Policy -->|REQUIRE_APPROVAL| Approval[Approval Center]
    Policy -->|ALLOW| Executor[Typed action executor]
    Approval -->|Approved| Executor
    Executor --> Email[IMAP/SMTP or local state]
    Executor --> Audit
    Audit --> Undo[Undo where supported]

Loading

The model never receives an email password and never owns a mailbox connection. It can return validated analysis and proposed actions only. Application code evaluates permissions, thresholds, protected senders, risk, and approval requirements before any executor is called.

See ARCHITECTURE.md for component and data-flow details.

Quick start on Windows

Requirements:

• Windows 10 or 11, x64
• Python 3.11 or newer available as python or through the Python launcher
• Internet access during installation
• Approximately 4 GB free disk space with the default local model

From D:\py34\MailMind:

install.bat
run.bat

install.bat is resumable and installs inside the project folder:

• .venv\ — Python and all application packages
• runtime\llama.cpp\ — official Windows x64 CPU runtime
• models\Qwen3-4B-Q4_K_M.gguf — default local model
• data\mailmind.db — migrated local database and demo data
• logs\ — redacted structured logs

To install the email client first without downloading the model:

install.bat --skip-ai
setup-ai.bat

Use run-console.bat when diagnosing startup issues.

Complete how-to-use guide

1. Install and launch

Open Command Prompt or PowerShell in the MailMind folder and run:

install.bat
run.bat

The installer is safe to run again if it was interrupted. It creates the Python environment, application runtime, local database and AI directories inside the project folder. It does not install an MSI, copy application files into Windows system folders, or move the mailbox outside the project.

For startup diagnostics, use:

run-console.bat

Keep that console open while reproducing a problem; it displays the error that should be included in a bug report.

2. Finish onboarding

On first launch, choose one of these paths:

• Add a real account to connect an IMAP/SMTP mailbox.
• Open the demo inbox to explore the interface without using real credentials or sending mail.

The demo is isolated from real accounts. It can later be reset or removed under Settings → Advanced.

3. Connect an email account

1. Open Accounts in the sidebar and select Add account.
2. Enter the email address, display name, and password or provider app password.
3. Let Quick setup fill the known provider settings, or open Manual settings and enter the IMAP and SMTP hosts, ports, and security modes supplied by the provider.
4. Select Test connection. MailMind tests incoming IMAP first and outgoing SMTP second.
5. When both tests succeed, select Add account.

Some providers disable password-based IMAP access or require an app password when two-factor authentication is enabled. Follow the provider's current account-security instructions. MailMind stores the resulting secret in Windows Credential Manager; the SQLite database contains only an opaque credential reference.

The Account enabled switch controls email synchronization and sending. AI access is a separate permission and can be changed without disconnecting email.

4. Synchronize the complete mailbox

Select the circular Sync button in the top bar. The first synchronization walks every selectable server folder from its oldest pending UID to its newest and imports messages in small batches. Large mailboxes can take several minutes. Keep MailMind open until the button returns to Synced and the completion notification appears.

Synchronization is incremental after the initial history import. If the connection drops during a large import, press Sync again; MailMind resumes from the last completed page. Existing messages are deduplicated, so retrying a sync is safe.

Newly imported mail appears in the local cache and remains readable offline. Use the account filter above the conversation list to show one account or the unified inbox.

5. Choose the AI permission for each account

Open Accounts and select an AI access mode for each account:

Mode	What it permits
Off	No email content from this account is submitted to the AI process. Pending analysis is cancelled.
Observe	Local classification and priority analysis; mailbox-changing proposals remain blocked.
Organize	Observe features plus policy-controlled importance, spam, move, and archive proposals.
Assist	Organize features plus task, draft, and send proposals. Sending still requires explicit approval.

Enabling Observe, Organize, or Assist queues existing unanalysed messages for that account. It does not start the model by itself. This separation lets you grant account permission while keeping the model stopped when you want to release memory.

6. Start and stop the local AI

1. Open Local AI in the sidebar.
2. Confirm that a model file is shown. If it is missing, close MailMind and run setup-ai.bat, or select Choose GGUF to use another compatible model.
3. Select Start AI and watch the states progress from checking the runtime to loading and then ACTIVE.
4. Optionally select Test endpoint to verify the local server.

Once the state is ACTIVE, queued messages are processed in the background. The Processed, Queued, and Failed cards show the current workload. You can continue reading and composing mail while this runs. Select Stop AI to release model memory; email and local search continue working.

Pause everywhere is an emergency global switch. It overrides every per-account mode until Resume AI is selected.

7. Read, search, and manage conversations

• Use Inbox for the main conversation list and All Accounts for the unified local view.
• Choose a conversation to open its safe, sanitized message view.
• Use All, Unread, and Priority above the list for quick filtering.
• Use the account selector to narrow results to one mailbox.
• Use the top search field for ordinary text or the filters documented in Search syntax.
• Use message actions to mark read, mark important, archive, create a task, or request reanalysis where available.

Remote images and tracking pixels remain blocked by default. Links require a deliberate user action before Windows opens them.

8. Compose, save, and send

1. Select Compose.
2. Choose the sending account and enter To, optional CC/BCC, subject, and message body.
3. Add files with Attach files if needed.
4. Select Save draft to keep a local draft, or Send to review the confirmation and transmit through the account's SMTP server.

The Professional, Friendlier, Shorter, Fix grammar, and Generate controls use the configured local AI endpoint to edit the draft. They never send the message. Manual sending occurs only after the Send action and its confirmation.

9. Use the intelligence views

• AI Priority groups the most important analysed conversations.
• Tasks shows extracted or manually created follow-up work and links back to its source email.
• Ask Inbox retrieves a small local source set and, when the AI is active, synthesizes an answer with clickable sources.
• Approvals lists proposals that the policy engine will not execute without confirmation.
• AI Activity is the audit trail for analysis, decisions, execution, failures, and undo.
• AI Rules converts a natural-language description into deterministic JSON. Inspect the preview, save it inactive, and activate it only after confirming its conditions and actions.

AI output is never direct authority. The deterministic policy engine checks the account mode, confidence threshold, protected senders, risk, and approval requirements before any action.

10. Review approvals and undo

Open Approvals whenever the sidebar indicates pending work. Inspect the source, proposed action, confidence, explanation, and risk before approving or rejecting it. Sending always requires an approval in the current source edition.

For a completed reversible action, open AI Activity and use its undo control when offered. Undo availability depends on the action and current provider state; sent email and some remote changes cannot be reversed.

11. Disconnect or remove an account

Open Accounts, select Remove, and choose carefully:

• Disconnect only removes the stored credential and disables the connection while preserving previously synchronized mail in the local cache.
• Remove cached data deletes that account's local MailMind records as well as disconnecting it.

Cached-data removal is destructive. Back up the project first if the local copy matters.

12. Back up or move the source edition

Close MailMind before copying its files. The important local state is under data\, while account secrets remain in Windows Credential Manager and therefore do not automatically move to another Windows account or computer. Copying the project preserves cached mail and settings, but real accounts may need to be reconnected on the destination machine.

To update dependencies after changing source or pyproject.toml, close MailMind and run install.bat again. The installer reuses the project-local environment.

Troubleshooting

Symptom	What to do
MailMind does not open	Run run-console.bat and inspect the final traceback. Run install.bat again if imports are missing.
Sending works but old mail is absent	Press Sync, wait for the completion notification, and retry once if the server interrupted the initial history import.
Account test fails	Recheck the manual IMAP/SMTP host, port, security mode, username, and provider app-password requirements.
Assist is selected but nothing processes	Open Local AI, start the model, confirm the status is ACTIVE, and make sure Pause everywhere is not enabled.
Local AI reports that runtime or model is missing	Close the app, run setup-ai.bat, then reopen it. Alternatively choose a compatible .gguf file.
Analysis remains queued	Confirm the account mode is not Off, the global AI switch is resumed, and the local endpoint test succeeds.
The application became slow during first setup	Let the historical sync and initial AI queue finish; both are one-time workloads and run in batches.
Database health is uncertain	Open Settings → Advanced → Validate local database.
A reproducible error remains	Start with run-console.bat, reproduce it once, and capture the traceback without including passwords or private message bodies.

Local model setup

The default is Qwen3-4B GGUF, Q4_K_M through llama.cpp. It is approximately 2.5 GB, uses an Apache-2.0 license, supports structured generation, and is a practical balance for ordinary Windows PCs.

The installer downloads both runtime and model into this repository. You can instead select any compatible .gguf file under Local AI → Choose GGUF, or point MAILMIND_AI_ENDPOINT at an existing OpenAI-compatible local server.

The dashboard exposes real process states:

Stopped → Checking runtime → Starting → Loading model → Ready
                                               ↘ Error / recovery
Ready → Stopping → Stopped

Stopping the AI process releases model memory. Email, local search, compose, drafts and cached reading remain available.

Email account setup

Go to Accounts → Add account. Quick detection includes Gmail, Microsoft, Yahoo and iCloud presets. Custom providers can be configured manually with:

• email address, display name and username
• IMAP host, port and SSL/TLS mode
• SMTP host, port and SSL/TLS mode
• password or provider app password

V1 intentionally supports app passwords rather than bundling provider-specific OAuth client secrets. Your provider may require IMAP access to be enabled. MailMind tests both incoming and outgoing connections before saving the account.

Demo mode

Choose Open demo inbox during onboarding. The seed includes:

• a revenue-impacting customer outage
• an interview invitation with an explicit response deadline
• an invoice, security notification and meeting change
• a support ticket, personal invitation and shipping update
• a newsletter and phishing-style spam message

The two demo accounts deliberately use different AI modes. They contain no credentials and cannot send external email.

Search syntax

Traditional search runs against the local cache and supports:

from:maya@example.com
to:alex@example.com
subject:checkout
account:northstar.studio
has:attachment
is:unread
is:important
priority:critical
category:security
before:2026-09-20
after:2026-09-01

Ask Inbox first retrieves a small relevant source set, then optionally asks the local model to synthesize an answer. Sources remain clickable.

Development

install.bat --skip-ai
.venv\Scripts\python.exe -m mailmind.bootstrap
run-console.bat

Useful checks:

test.bat
.venv\Scripts\python.exe -m ruff check .
.venv\Scripts\python.exe -m mypy mailmind
.venv\Scripts\python.exe -m alembic upgrade head

The optional loopback API can be started for diagnostics:

.venv\Scripts\python.exe -m uvicorn mailmind.api:app --host 127.0.0.1 --port 8765

Do not expose that development API beyond loopback without adding authentication and transport security.

Privacy model

• Mail content is cached locally for offline access.
• Remote image URLs are removed from rendered messages by default.
• HTML is allowlisted and sanitized before it reaches the viewer.
• Secrets are stored in the OS credential vault and represented by opaque references in SQLite.
• AI permissions are per account, plus a global pause switch.
• Prompt construction explicitly separates system policy, trusted user configuration and JSON-encoded untrusted email content.
• Logs redact secret-bearing keys and bearer-token patterns and avoid full message bodies.
• AI-generated output is schema-validated; malformed output fails closed.

Read SECURITY.md before extending provider or action code.

Tests

The suite covers high-value boundaries:

• Policy Engine permissions, thresholds, sending approval and protected senders
• strict AI schemas and explicit-deadline separation
• prompt-injection boundaries
• HTML sanitization and tracking-image blocking
• credential/log redaction
• MIME parsing and attachments
• deterministic rule evaluation
• search filters
• action execution/undo and demo isolation

Roadmap

• Provider OAuth adapters for Google and Microsoft
• richer IMAP flags and server-side folder mutation reconciliation
• OS notifications with per-account quiet hours
• incremental FTS5 and optional dedicated embedding model
• attachment text extraction behind explicit per-account permission
• provider-specific threading improvements
• signed auto-update channel after packaging is introduced

Limitations

• Provider OAuth is not bundled; use app passwords in V1.
• IMAP implementations vary. The generic provider covers common servers but will need field testing against organization-specific folder conventions and auth policies.
• Undo of remote mailbox operations depends on provider state and may not be possible after external changes.
• The default CPU llama.cpp runtime favors compatibility over maximum GPU performance. Advanced users may substitute a Vulkan/CUDA build.
• Ask Inbox currently uses lightweight lexical retrieval. The embedding interface is present, but a separate embedding model is not downloaded by default.
• Desktop notifications and full remote-draft synchronization are roadmap items; local drafts already work offline.
• Source-only delivery is intentional. No MSI/EXE installer is generated.

License

MailMind source is provided under the MIT License. Third-party runtimes and models keep their own licenses; review them before redistribution.