Support this project! All donations go towards your chosen charity. You can pick any charity you'd like, and 5% is retained due to Ko-Fi fees. As a thank you, your name will be listed as a supporter/donor in this project. Feel free to email me at thedjskywalker@gmail.com for proof! :)
AutoSort+
AI-Powered Email Organization for Thunderbird
Let AI help you organize your emails intelligently.
Not yet in Thunderbird Add-on Store - Manual installation required. Official store submission in progress.
Download * Documentation * Report Bug * Request Feature
Table of Contents
- Features
- Installation
- Quick Start
- AI Provider Setup
- Usage
- Technical Details
Troubleshooting - Changelog
- Contributing
Features
Multi-Provider AIChoose from 5 leading cloud AI providers or run a local Ollama model:
|
Multiple API Keys (Gemini)
|
Smart Folder Management
|
Intelligent Classification
|
Additional Features
- Secure Storage - Encrypted API key storage
- Batch Processing - Sort multiple emails at once
- Rate Limiting - Built-in quota management (Gemini)
- Professional UI - Clean, intuitive interface
- Move History - Track all email movements
- Real-time Validation - Instant feedback
- Open Source - Transparent, auditable code
Installation
Option 1: Download Release (Recommended)
1. Visit: https://github.com/Nigel1992/AutoSort-Plus/releases
2. Download: autosortplus.xpi
3. Thunderbird: Tools - Add-ons and Extensions
4. Click: - Install Add-on From File
5. Select: autosortplus.xpi
6. Restart Thunderbird
2. Download: autosortplus.xpi
3. Thunderbird: Tools - Add-ons and Extensions
4. Click: - Install Add-on From File
5. Select: autosortplus.xpi
6. Restart Thunderbird
Option 2: Build from Source
git clone https://github.com/Nigel1992/AutoSort-Plus.git
cd AutoSort-Plus
zip -r autosortplus.xpi manifest.json background.js options.js options.html styles.css content.js icons/
cd AutoSort-Plus
zip -r autosortplus.xpi manifest.json background.js options.js options.html styles.css content.js icons/
Download Latest Release * View Changelog
Quick Start
1 Choose AI Provider
Open settings and select from Gemini, OpenAI, Claude, Groq, Mistral, or Ollama (Local LLM)
2 Get API Key (or install local Ollama)
Click "Get API Key" button - Create free account - Copy key. For Ollama (local): install Ollama from https://ollama.ai/download and pull a model (e.g., ollama pull llama3.2). No API key required for Ollama.
3 Configure Folders
Load folders from IMAP or add custom labels
4 Sort Emails (Two Options)
Option 1: AI-Powered Sorting
- Select emails - Right-click - AutoSort+ - Analyze with AI
- The AI will analyze and move emails to the best folder/category.
Option 2: Manual Labeling
- Select emails - Right-click - AutoSort+ - AutoSort Label - [Pick any label]
- The selected label/category will be applied instantly to all selected emails.
Warning: If you add or change labels in the settings menu, you must restart Thunderbird for the new labels to appear in the right-click menu.
Note: Currently requires manual selection and right-click. Automatic background sorting coming in future update!
AI Provider Setup
AI Provider Setup
| Provider | Get API Key | Free Tier | Best For |
|---|---|---|---|
| Gemini | Get Key | 20/day per key | Best overall free option |
| Groq | Get Key | 30/min | Speed & high limits |
| Claude | Get Key | Limited | Privacy & safety |
| OpenAI | Get Key | Highest accuracy | |
| Mistral | Get Key | Limited | GDPR compliance |
| Ollama | Install Ollama | Local (no external usage) | Run local LLMs (llama3.2, tinyllama, phi, gemma). No API keys required; supports model downloads and CPU-only mode. |
Usage Limits & Recommendations
IMPORTANT: Free tiers are limited for email processing due to large text content.
| Provider | Free Limit | Recommendation |
|---|---|---|
| Gemini | 20 emails/day per API key | Create multiple keys in different projects |
| Groq | 20-30 emails/day | Best free tier overall |
| Claude | 10-15 emails/day | Good for privacy-conscious users |
| OpenAI | 5-10 emails/day | Consider paid plan ($5-20/mo) |
| Mistral | 10-15 emails/day | Best for EU users |
Tips for Managing Free Tier Limits
For Gemini users (NEW in v1.2.1!):
- [NEW] Multiple API Keys: Add keys from different Google Cloud projects
- Automatic Rotation: Extension switches keys when limits are reached
- Per-Key Tracking: Monitor usage for each key independently
- Example: 5 keys = 100 requests/day total (20 per key)
- How to add: Settings - Add Another Gemini Key
- Check usage: AI Studio Usage
For all providers:
- Process emails in small batches
- Use "Gemini paid plan" checkbox to disable limits (if you have paid tier)
- Consider paid plans for daily use ($5-20/month)
Usage
Basic Operation
- Select Emails - Click one or more emails in Thunderbird
- Right-Click Menu - Right-click - AutoSort+ - Analyze with AI
- Smart Sorting - AI analyzes and moves emails to appropriate folders
- Track History - View last 100 moves in settings
Coming Soon: Automatic background sorting (currently manual via right-click)
Advanced Features
Multiple API Keys (Gemini - NEW!)
- Add unlimited keys from different projects
- Automatic rotation when limits reached
- Individual testing and status tracking
- Visual indicators (Active, Ready, Near Limit)
- Combined quota = keys x 20 requests/day
Usage Monitoring (Gemini)
- Real-time usage display in settings
- Per-key usage statistics
- Automatic warnings at 15/20 limit
- Smart key rotation
Folder Management
- Load folders from IMAP accounts
- Bulk import from text list
- Create custom categories
- Auto-create missing folders
Move History
- Last 100 email moves
- Timestamps and destinations
- Success/failure status
- Clear history option
Manual Labeling (Right-Click)
You can also manually label emails without AI analysis:
- Select Emails - Click one or more emails in Thunderbird.
- Right-Click Menu - Right-click - AutoSort+ - AutoSort Label - [Pick any label]
- Label Applied - The selected label/category will be applied to all selected emails instantly.
Note: If you add or change labels in the settings menu, you must restart Thunderbird for the new labels to appear in the right-click menu.
Example Folder Categories
Work & Professional:
- Meetings
- Project Updates
- Invoices
- HR & Benefits
Financial:
- Bills & Payments
- Bank Statements
- Receipts
- Tax Documents
Personal:
- Family
- Friends
- Health
- Travel
Online Services:
- Shopping Confirmations
- Social Media Notifications
- Subscriptions
- Password Resets
Promotions:
- Newsletters
- Sales & Discounts
- Offers
- Marketing
Support:
- Tickets & Help
- Documentation
- Updates
- Complaints
Technical Details
System Architecture
+-----------------------------------------+
| Thunderbird Email Client |
+--------------+--------------------------+
|
+--------------V--------------------------+
| AutoSort+ Extension |
| |
| +----------+ +----------+ |
| | UI Layer | | Background| |
| |(options) |<-+ Script | |
| +----------+ +-----+-----+ |
| | |
| +-------V--------+ |
| | Rate Limiter | |
| | (Gemini only) | |
| +-------+--------+ |
+----------------------+-----------------+
|
+-------------+-------------+
| |
+----V----+ +--------+ +-----V-----+
| Gemini | | Groq | | Claude |
| API | | API | | API |
+---------+ +--------+ +-----------+
File Structure
| File | Purpose | Key Functions |
|---|---|---|
background.js |
AI analysis engine | analyzeEmailContent(), rate limiting |
options.js |
Settings UI | Provider config, usage display |
content.js |
Email extraction | Message content parsing |
manifest.json |
Extension config | Permissions, metadata |
Storage Schema
{
// User Configuration
apiKey: "string",
aiProvider: "gemini|openai|anthropic|groq|mistral",
labels: ["Work", "Personal", ...],
enableAi: boolean,
geminiPaidPlan: boolean,
// Rate Limiting (Gemini)
geminiRateLimit: {
requests: [timestamp, ...],
dailyCount: number,
dailyResetTime: timestamp
},
// History
moveHistory: [
{
timestamp: string,
subject: string,
status: string,
destination: string
},
...
]
}
// User Configuration
apiKey: "string",
aiProvider: "gemini|openai|anthropic|groq|mistral",
labels: ["Work", "Personal", ...],
enableAi: boolean,
geminiPaidPlan: boolean,
// Rate Limiting (Gemini)
geminiRateLimit: {
requests: [timestamp, ...],
dailyCount: number,
dailyResetTime: timestamp
},
// History
moveHistory: [
{
timestamp: string,
subject: string,
status: string,
destination: string
},
...
]
}
Supported AI Models
| Provider | Model | Context Window | Speed | Cost |
|---|---|---|---|---|
| Gemini | gemini-2.5-flash | 1M tokens | Free/Paid | |
| OpenAI | gpt-4o-mini | 128K tokens | Paid | |
| Claude | claude-3-haiku | 200K tokens | Free/Paid | |
| Groq | llama-3.3-70b | 8K tokens | Free | |
| Mistral | mistral-small-latest | 32K tokens | Free/Paid | |
| Ollama (Local) | llama3.2, phi, gemma, tinyllama (varies) | Varies by model (local) | - | Local (no external cost) |
Note: Ollama runs locally on your machine -- no API key required. Models are downloaded via
ollama pulland can run in CPU-only mode for machines without GPU resources.
Privacy & Security
| Feature | Status | Details |
|---|---|---|
| API Key Storage | Encrypted | OS-level encryption via browser storage |
| Email Content | Not Stored | Analyzed in memory, never persisted |
| Data Transmission | Direct to AI | No intermediary servers |
| Telemetry | None | Zero tracking or analytics |
| Open Source | Auditable | Full transparency |
| Permissions | Minimal | Only required APIs |
Your privacy matters: All email analysis happens directly between your Thunderbird and chosen AI provider. No data passes through our servers because we don't have any!
Settings Page Won't Load
1. Thunderbird - Settings - Privacy - Cookies and Site Data
2. Click "Clear Data"
3. Tools - Add-ons - AutoSort+ - Reload
2. Click "Clear Data"
3. Tools - Add-ons - AutoSort+ - Reload
API Key Not Working
- Verify key is copied correctly (no spaces)
- Click "Test API Connection" button
- Check key is from correct provider
- Ensure API key has proper permissions
- For Gemini: Check usage page
Email Analysis Fails
Check:
- Internet connection active
- API key is valid
- Provider status page for outages
- Rate limits not exceeded
- Email content isn't empty
For Gemini users:
- Check usage counter in settings
- Verify daily limit not reached (20/day)
- Switch to new API key if needed
Wrong Labels Applied
- Ensure labels are case-sensitive matches
- Avoid special characters in folder names
- Verify labels are saved (green checkmark)
- Check move history for patterns
Rate Limit Errors
Gemini (20/day per key):
- Create new API key in different project
- Reset counter after switching keys
- Enable "paid plan" option if you have one
Other Providers:
- Wait for rate limit window to reset
- Consider upgrading to paid tier
- Use provider's usage dashboard
System Requirements
| Component | Requirement |
|---|---|
| Thunderbird | 78.0 or later |
| Internet | Active connection for API calls |
| API Key | Valid key from chosen provider |
| Storage | ~1MB for extension data |
| OS | Windows, macOS, Linux |
Changelog
v1.2.0 (2026-01-13) - Multi-Provider Release
[NEW] New Features
- Multi-provider AI support (5 providers)
- Gemini rate limiting (5/min, 20/day enforcement)
- Real-time usage tracking dashboard
- IMAP folder auto-discovery
- Bulk label import
- Move history (last 100 entries)
- Professional UI redesign
- Provider info cards
Improvements
- Groq updated to llama-3.3-70b
- Better error handling and validation
- Auto-create missing folders
- Skip null categories
- Batch email processing fixes
- Professional funnel/envelope icons
- Example folder categories
Technical Changes
- Unified API key storage
- Settings validation system
- Recursive folder traversal
- Fixed syntax errors in options.js
- Improved state management
v1.0.0 (2026-01-10) - Initial Release
- Initial release with Gemini support
Roadmap & TODO
| Priority | Feature | Status |
|---|---|---|
| High | Detailed Logging - Debug mode with console output | Planned |
| High | API Response Headers - Extract rate limit info from API | Planned |
| Medium | Smart Key Switching - Auto-suggest when to switch keys | Proposed |
| Medium | Scheduled Processing - Auto-sort at specific times | Proposed |
| Low | Custom Rules - User-defined sorting logic | Proposed |
| Low | Statistics Dashboard - Email sorting analytics | Proposed |
Known Issues
None currently reported!
If you encounter any issues, please open an issue on GitHub.
Support & Community
| Questions | Bug Reports | Feature Requests |
|---|---|---|
| Discussions | Issues | Issues |
Before reporting:
- Check Troubleshooting section
- Search existing issues
- Include Thunderbird version and extension version
Contributing
We welcome contributions! Here's how to help:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing) - Commit your changes (
git commit -m 'Add amazing feature') - Push to branch (
git push origin feature/amazing) - Open a Pull Request
Guidelines:
- Follow existing code style
- Add comments for complex logic
- Test with multiple AI providers
- Update README for new features
License
MIT License
Copyright (c) 2026 Nigel
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
See LICENSE file for full text.
Credits & Acknowledgments
Icon Design:
Email filtering icons created by Fantasyou - Flaticon
AI Providers:
Built with:
- Thunderbird WebExtension APIs
- JavaScript ES6+
- Manifest v2
Star History
Made with to help you organize email faster
Back to Top * GitHub * Latest Release * Documentation