Battle-tested email archaeology application that allows you to search and compile reports from multiple accounts. NeuralMail does not let you compose or sent emails, it tackles the problem of finding things of which you know they "must be in some email".
- Multiple IMAP Account Support 💼: Manage and search across multiple email accounts simultaneously.
- Smart Search 🔍: Use natural language to search through your emails and their attachments, build reports.
- Attachment Processing 📎: Automatically extracts and processes text from PDF and DOCX attachments.
- Deep Research Mode 🧠: Agent-based analysis mode that performs thorough research across your emails.
- Creates a user profile for improved retrieval 👤: Context engineering to give the model more relevant concepts.
- Parallel Processing ⚡: Efficient email synchronization and deep research using parallel processing
- Modern UI 🎨: Clean, cross-platform UI
- Local Storage 💾: All data stored locally for privacy and quick access; LLMs can be local or remote (OpenAI compatible API provider); Gemini Flash gives a great performance / cost balance.
- Warning
⚠️ : IMAP passwords and API keys are currently stored unencrypted in a local configuration file.
- Python 3.8 - 3.12
- OpenAI API key or compatible local provider; Works great with Gemini Flash through OpenRouter for optimal performance/cost balance
- IMAP email account(s)
- Create and activate a virtual environment:
# On Windows
python -m venv venv
venv\Scripts\activate
# On macOS/Linux
python3 -m venv venv
source venv/bin/activate- Install directly from source:
pip install git+https://github.com/jmrk84/neuralmail.gitOr if you have the source code locally:
git clone https://github.com/jmrk84/neuralmail.git
cd neuralmail
pip install .If you want to contribute or modify the code:
- Clone and install in editable mode:
git clone https://github.com/jmrk84/neuralmail.git
cd neuralmail
pip install -e .- Launch the application:
neuralmail-
First-time setup:
- Click "Add Account" to configure your first email account
- Enter your IMAP server details (host, port, username, password)
- Add your API key
- Select which email folders to sync
- Click "Save Settings"
-
Basic usage:
- Click "Sync Emails" to download and process your emails (auto-sync on startup and in intervalls)
- Enter a natural language query in the search box
- Choose between "Quick Search" or "Deep Research" mode
-
Gmail:
- Host: imap.gmail.com
- Port: 993
- SSL: Enabled
- Note: Requires "App Password" if 2FA is enabled
-
Outlook:
- Host: outlook.office365.com
- Port: 993
- SSL: Enabled
- Each account uses a separate SQLite database
- Default location:
emails_[account_number].db - Can be configured to custom location
neuralmail/main.py: Main application file with GUIneuralmail/parallel_email_sync.py: Parallel email synchronization implementationneuralmail/deep_research_worker.py: Deep research mode implementationneuralmail/research_tools.py: Research utilities and toolsneuralmail/model_interface.py: OpenAI/LLM API interfaceneuralmail/research_agent.py: Intelligent research agent implementationneuralmail/config.py: Configuration managementneuralmail/utils.py: Utility functionssetup.py: Package installation configuration
- Fork the repository
- Create a feature branch
- Make your changes
- Test the app properly
- Submit a pull request
- Email credentials and API keys are stored locally in
config.json
This project is licensed under the MIT License - see the LICENSE file for details.
Please feel free to create github issues and pull request. Contributions welcome! I'd love if the functionality got integrated into K9-mail, Thunderbird or any other open-source client.