📧 MailMind

Your Email System Can Finally Do Jobs For You!

An AI-powered email agent that combines large language models with modern email system.

MailMind helps you read, organize, draft, and manage emails through an intuitive chat interface.

Quick Start • Features • Contacts • Documentation • Contributing • 中文文档

🎉 What's New in v0.0.5

📚 Knowledge Base & Temporary File Upload

We've added powerful file management capabilities to enhance your AI experience!

Knowledge Base Feature:

📁 Document Management - Upload, create, edit, and delete knowledge documents
📄 Multi-Format Support - Supports .txt, .md, .docx, .pdf, and .doc files
🔄 Auto Conversion - .docx, .pdf, and .doc files automatically converted to .md for AI compatibility
✏️ In-App Editing - Edit .txt and .md files directly in the browser
🎯 Persistent Context - Knowledge base files are always accessible to AI across all sessions

Temporary File Upload:

💬 Session-Specific Files - Upload files specific to each chat session
📂 Agent Filesystem Access - Files are stored in agent's filesystem at temp_uploads/
🔧 Tool Integration - AI can read and process uploaded files using file tools
🚀 Instant Availability - Files immediately available without agent reload
🗑️ Easy Management - Delete temporary files with one click

How It Works:

Knowledge Base:

Navigate to the Knowledge page
Upload documents (.txt, .md, .docx, .pdf, .doc) or create new text files
Edit content directly in the browser
AI automatically has access to all knowledge base documents

Temporary Files (Chat):

In the Chat page, click the Add File button next to the input box
Select a file to upload (max 10MB, same formats as knowledge base)
File appears as a tag above the input box
AI can access the file via its filesystem tools during the session

✨ Features

🤖 AI-Powered Email Agent Natural language interaction Context-aware responses Intelligent email processing Automated workflows with smart planning	📧 Intelligent Email Box Read, compose, send emails Organize emails by AI Extract information by intuition Generate communication flows
👥 AI-accessable Contacts Create and edit contacts Automatically organize by AI AI-understood social networks Powerful search and filtering	🔍 Smart Capabilities Web search integration Multi-session support Real-time streaming Attachment handling
📚 Knowledge Base Upload & manage documents Multi-format support (.txt, .md, .docx, .pdf, .doc) Auto conversion to .md In-app editing for text files Global AI access across sessions	📎 Temporary File Upload Session-specific file uploads Agent filesystem integration Files accessible via tools Instant availability Easy file management

🏗️ Architecture

Backend Stack

FastAPI    → High-performance async web framework
LangGraph  → Advanced agent orchestration
WebSocket  → Real-time bidirectional communication
IMAP/SMTP  → Direct email protocol integration

Frontend Stack

React 18      → Modern UI with hooks
TypeScript    → Type-safe development
Tailwind CSS  → Utility-first styling
Vite          → Lightning-fast build tool
Axios         → HTTP & WebSocket client

AI Integration

OpenAI-Compatible APIs - Support for multiple LLM providers
Tavily Search - Web search capabilities
Subagent Architecture - Specialized task handling
Context Management - Smart conversation tracking

🚀 Quick Start

Prerequisites

Node.js 18+ and npm
Python 3.10+
Email account with IMAP access (Gmail recommended)
API keys for your chosen LLM provider

Installation

1. Clone the repository

git clone https://github.com/yourusername/mailmind.git
cd mailmind

2. Configure environment variables

cd web_app
cp .env.example .env
# Edit .env with your API keys and email credentials

3. Start the application

./start.sh

The startup script will automatically:

✅ Install Python dependencies in a virtual environment
✅ Install Node.js dependencies
✅ Start the backend server (default: http://localhost:2821)
✅ Start the frontend dev server (default: http://localhost:2922)

4. Open your browser

Navigate to http://localhost:2922 and start managing your emails with AI!

⚙️ Configuration

Model Settings

Variable	Description	Example
`MODEL`	Model name	`gpt-4`, `claude-3-sonnet`
`OPENAI_API_KEY`	Your API key	`sk-...`
`OPENAI_BASE_URL`	API endpoint	`https://api.openai.com/v1`
`DISPLAY_REASONING`	Show reasoning	`True`/`False`

Email Settings

Variable	Description	Default
`USERNAME`	Your email address	-
`PASSWORD`	App-specific password	-
`IMAP_SERVER`	IMAP server address	`imap.gmail.com`
`SMTP_SERVER`	SMTP server address	`smtp.gmail.com`
`IMAP_PORT`	IMAP port	`993`
`SMTP_PORT`	SMTP port	`465`

Tested Email Providers

Provider	Status	Notes
✅ Gmail	Fully Tested & Supported	Requires App Password. Enable IMAP in settings.
🔄 Outlook	In Testing	Very complicated access through IMAP and SMTP protocols.

Gmail Setup Guide (Recommended)

Enable 2-Factor Authentication
- Go to Google Account settings
- Security → 2-Step Verification
- Enable 2FA
Generate App Password
- Go to Google Account settings
- Security → App passwords
- Generate new app password
- Use this password in PASSWORD field
Enable IMAP Access
- Go to Gmail settings
- Forwarding and POP/IMAP
- Enable IMAP
- Save changes

Configure MailMind

USERNAME=yourname@gmail.com
PASSWORD=[your 16-character app password]
IMAP_SERVER=imap.gmail.com
SMTP_SERVER=smtp.gmail.com
IMAP_PORT=993
SMTP_PORT=465

Network Settings

Variable	Description	Default
`BACKEND_PORT`	Backend server port	`2821`
`FRONTEND_PORT`	Frontend dev server port	`2922`

💡 Usage

Chat Interface

Start a Conversation - Type your request in natural language:

"Summarize my unread emails"
"Reply to all unread New Year greeting emails"
"Delete all emails from newsletter@example.com"

Watch the AI Work - See the agent's thought process and tool calls in real-time
Manage Multiple Sessions - Create new chat sessions for different tasks

Email Management

Action	Description
📖 Read	Fetch and display emails with filtering
✉️ Send	Compose and send new emails
🗑️ Delete	Remove unwanted emails
📁 Move	Organize emails into folders
🏴 Flag	Mark as important/unread
📎 Attachments	View and download files

Contacts Management

Organize your contacts efficiently with our comprehensive contacts feature:

Feature	Description
👤 Add Contacts	Create new contacts with multiple email addresses
✏️ Edit Contacts	Update contact information anytime
🗑️ Delete Contacts	Remove contacts with confirmation
🏷️ Groups	Organize contacts into custom groups
🔍 Search	Find contacts by name, email, or group
📋 Alphabetical View	Contacts automatically sorted by first letter

Benefits:

📧 Quick access when composing emails
🎯 Filter emails by contacts
👥 Organize contacts into groups (Family, Work, Friends, etc.)
🔎 Search across all contact fields instantly

Settings Page

Configure everything through the web UI:

🔑 Update API keys
📧 Configure email servers
🔌 Adjust network ports
🎨 Toggle display options

Contacts Page

Manage your network of contacts efficiently:

Adding Contacts:

Click the "Add Contact" button
Enter contact name (required)
Add one or more email addresses
Assign to groups (e.g., Family, Work, Friends)
Save the contact

Organizing with Groups:

Create custom groups to categorize contacts
Filter contacts by group in the sidebar
Groups show contact counts
Easily add/remove contacts from groups

Searching Contacts:

Search by name, email, or group
Real-time filtering as you type
Alphabetically sorted display
Quick access to contact details

Managing Contacts:

✏️ Edit any contact to update information
🗑️ Delete with confirmation dialog
📧 Multiple email addresses per contact
🏷️ Visual group tags on each contact

📁 Project Structure

mailmind/
├── deepagents/              # Core agent framework
│   ├── backends/           # Backend implementations
│   ├── middleware/         # Agent middleware
│   └── ...
├── lib/                    # Shared utilities
│   ├── email_tools.py     # Email operations
│   ├── prompt.py          # System prompts
│   └── ...
├── web_app/               # Web application
│   ├── backend/          # FastAPI server
│   │   ├── api_server.py
│   │   └── requirements.txt
│   ├── frontend/         # React + TypeScript UI
│   │   ├── src/
│   │   │   ├── components/   # UI components
│   │   │   ├── pages/        # Page components
│   │   │   ├── lib/          # API & utilities
│   │   │   └── contexts/     # React contexts
│   │   ├── package.json
│   │   └── vite.config.js
│   └── start.sh         # Startup script
├── .env.example          # Environment template
└── README.md            # This file

🛠️ Development

Backend Development

cd web_app/backend
source venv/bin/activate  # Activate virtual environment
python api_server.py      # Start with auto-reload

Frontend Development

cd web_app/frontend
npm run dev     # Start dev server with hot reload
npm run build   # Build for production
npm run preview # Preview production build

Quick Development of Agent

python lib/test.py

🔑 Key Features Explained

Session Isolation

Each chat session maintains:

✅ Separate agent instance with isolated state
✅ Independent email cache
✅ Dedicated filesystem for file operations
✅ Unique conversation history

Real-Time Streaming

✅ WebSocket connection for instant communication
✅ Stream agent responses token-by-token
✅ Display tool calls and results as they happen
✅ Visual feedback for agent status

Email Cache Persistence

✅ Caches persisted to .emails_cache.json
✅ Survives server restarts
✅ Automatically cleaned up on session deletion
✅ Session-isolated to prevent cross-contamination

🔧 Troubleshooting

Email Connection Issues

Gmail-specific issues

Use an App Password instead of your regular password
Enable IMAP access in Gmail settings
Check "Less secure app access" if applicable
Verify 2FA is enabled (required for App Passwords)

General email issues

Check firewall/proxy settings if using a proxy
Verify IMAP/SMTP server addresses and ports
Ensure ports 993 (IMAP) and 465/587 (SMTP) are open
Test connection with telnet imap.gmail.com 993

API Errors

Common API issues

Verify API key is valid and has sufficient credits
Check that OPENAI_BASE_URL is correct for your provider
Some providers require specific model names
Check rate limits and quota usage
Review error messages in backend logs

WebSocket Connection

Connection problems

Ensure backend is running and accessible
Check port conflicts in .env
Verify browser console for errors
Try refreshing the page
Check network tab in browser DevTools

Performance Issues

Slow performance

Reduce email batch size in read_emails tool
Close unused chat sessions
Clear browser cache if UI is slow
Check system resources (CPU, memory)
Monitor network tab for large payloads

🔒 Security Considerations

⚠️ Important Security Notes:

❌ Never commit .env file to version control
🔑 Use App Passwords for email authentication
🔄 Keep API keys secure and rotate regularly
⚠️ Be cautious with proxy configurations
🌐 The app runs locally; avoid exposing ports to the internet
📁 Check .gitignore to ensure sensitive files are excluded

📝 TODO List

Email Box - Intelligent email client interface
User File Upload - Upload files for AI chat ✅ (v0.0.5)
Long-term Memory - Store and retrieve conversation facts
Advanced Search - AI-powered categorization
Multi-Account Support - Multiple email accounts
Email Analytics - Statistics dashboard
AI Summaries - Thread summarization
Calendar Integration - Google Calendar & Outlook
More LLM APIs - Anthropic, Cohere, etc.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

🙏 Acknowledgments

Built with amazing open-source tools:

DeepAgents - Agent orchestration
React - UI framework
Tailwind CSS - Styling
Lucide - Icons
imap-tools - Email operations
FastAPI - Backend framework

Name		Name	Last commit message	Last commit date
deepagents		deepagents
lib		lib
pics		pics
web_app		web_app
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
KNOWLEDGE_BASE_README.md		KNOWLEDGE_BASE_README.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
README_CN.md		README_CN.md
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Latest commit

History

Folders and files

Repository files navigation