🎯 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 AI Choose from 5 leading cloud AI providers or run a local Ollama model: Google Gemini - Best free tier + Multi-key support OpenAI - Superior accuracy Anthropic Claude - Privacy-focused Groq - Fastest processing Mistral AI - GDPR compliant Ollama (Local) - Run LLMs locally (llama3.2, tinyllama, phi, gemma). No API key required; supports model download and CPU-only mode	🔑 Multiple API Keys (Gemini) Add keys from multiple projects Automatic rotation on limit Per-key usage tracking 5 keys = 100 requests/day
📁 Smart Folder Management IMAP folder auto-discovery Bulk label import Custom folder creation Recursive traversal	🎯 Intelligent Classification Content analysis Context-aware sorting Multi-label support 100-entry history

🔥 Additional Features

• ✅ Secure Storage - Encrypted API key storage
• ✅ Batch Processing - Sort many emails in parallel with a live progress panel (cancel / retry failed)
• ✅ Bulk Key Import - Add many Gemini keys at once with duplicate detection
• ✅ Toolbar Popup - Quick API usage summary with shortcuts to Settings and Batch Panel
• ✅ Dark Mode - Full dark-theme support across all screens
• ✅ 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

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/

📥 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+ → Batch 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	⚠️ $5 credit	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!):

• 🆕 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

1. Select Emails - Click one or more emails in Thunderbird
2. Right-Click Menu - Right-click → AutoSort+ → Batch Analyze with AI
3. Smart Sorting - A Batch Panel tab opens with a live progress bar; the AI analyzes and moves each email to the appropriate folder. You can Cancel at any time, or Retry Failed emails when it finishes
4. Track History - View last 100 moves in settings

🔄 Coming Soon: Automatic background sorting (currently manual via right-click)

Advanced Features

� Multiple API Keys (Gemini)

• Add unlimited keys from different projects
• Bulk import many keys at once (one per line) with duplicate detection
• Automatic rotation when limits reached
• Individual testing and status tracking
• Visual indicators (Active, Ready, Near Limit)
• Combined quota = keys × 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

🗂️ Batch Processing

• Right-click → Batch Analyze with AI to sort many emails
• Live progress panel with per-email results
• Parallel analysis — Parallel batch size is configurable (1–20) in Settings
• Cancel anytime, or retry only the failed emails

Manual Labeling (Right-Click)

You can also manually label emails without AI analysis:

1. Select Emails - Click one or more emails in Thunderbird.
2. Right-Click Menu - Right-click → AutoSort+ → AutoSort Label → [Pick any label]
3. 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        │
└──────────────┬──────────────────────────┘
               │
┌──────────────▼──────────────────────────┐
│        AutoSort+ Extension              │
│                                         │
│  ┌──────────┐  ┌──────────┐           │
│  │ UI Layer │  │ Background│           │
│  │(options) │◄─┤  Script   │           │
│  └──────────┘  └─────┬─────┘           │
│                      │                  │
│              ┌───────▼────────┐        │
│              │  Rate Limiter  │        │
│              │  (Gemini only) │        │
│              └───────┬────────┘        │
└──────────────────────┼─────────────────┘
                       │
         ┌─────────────┴─────────────┐
         │                           │
    ┌────▼────┐  ┌────────┐  ┌─────▼─────┐
    │ 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,
  geminiModel: "string",   // e.g. "gemini-3.5-flash-lite"
  providerModel: "string", // optional model override for non-Gemini providers
  
  // Rate Limiting (Gemini)
  geminiRateLimit: {
    requests: [timestamp, ...],
    dailyCount: number,
    dailyResetTime: timestamp
  },
  
  // History
  moveHistory: [
    {
      timestamp: string,
      subject: string,
      status: string,
      destination: string
    },
    ...
  ]
}

🔒 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!

---

⚠️ Troubleshooting

🔧 Settings Page Won't Load

1. Thunderbird → Settings → Privacy → Cookies and Site Data
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.4.0 (2026-10-17) - Batch Panel, Bulk Key Import, Dark Mode & Quick Popup

🆕 New Features

• ✅ Batch progress panel - "Batch Analyze with AI" opens a dedicated panel with a live progress bar, per-email results (sorted / skipped / failed), running counts, and live per-key API usage cards. Includes Cancel and Retry Failed only controls, and re-syncs automatically if you reopen the tab
• ✅ Parallel batch processing - Emails are analyzed concurrently in chunks (5 at a time by default, configurable 1–20 in Settings → General Settings) so large batches finish much faster, with per-key usage counting kept correct
• ✅ Bulk import Gemini API keys - Paste many keys at once (one per line) into Settings → Multiple Gemini API Keys → Bulk Import with duplicate detection, instead of adding them one at a time
• ✅ Toolbar popup - Click the AutoSort+ toolbar icon for an at-a-glance API usage summary (aggregated across all Gemini keys) with quick buttons to open Settings and the Batch Panel
• ✅ Dark mode - Full dark-theme support across Settings, the popup, and the Batch Panel (follows your OS/Thunderbird color scheme)

🐛 Bug Fixes

• ✅ Accurate AI call counting - One email now uses exactly one API request; retries no longer re-analyze the same email (previously batches could over-consume quota)
• ✅ More reliable email content extraction - HTML bodies are now properly converted to text (the conversion is awaited) and messages without MIME parts are handled, so fewer emails are skipped
• ✅ Fixed rateLimit is undefined - Per-key Gemini usage is now normalized with safe defaults
• ✅ Fixed usage race condition - Concurrent requests could clobber the per-key daily counter; a lock now serializes reads/writes so batch usage is counted correctly

🎉 v1.3.0 (2026-10-16) - LM Studio Support (test)

• ✅ Added LM Studio as a local LLM provider (native REST API, optional Bearer token)
• ✅ List Models / Test Connection buttons and tolerant Server URL handling

v1.2.5 - Configurable AI Models

• ✅ Gemini 404 on new API keys fixed (default model now gemini-3.5-flash-lite)
• ✅ Choose your Gemini model (with Load Available Models); optional model override for other providers
• ✅ Gemini 3.x thinkingLevel support

v1.2.4 - Groq Model Update

• ✅ Groq updated to the supported openai/gpt-oss-120b

v1.2.3 - Toolbar Icon & Manual Labeling Fixes

• ✅ Toolbar icon for one-click settings access
• ✅ Manual label application via right-click works in all views

v1.2.2 - Bug Fixes & Error Messages

• ✅ Fixed single-key usage display and rate-limit notifications
• ✅ Clearer API test feedback (429/401/403) and hover tooltips

v1.2.1 - Multiple Gemini API Keys

• ✅ Add multiple keys with automatic rotation and per-key usage tracking

🎉 v1.2.0 (2026-01-13) - Multi-Provider Release

🆕 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:

1. Check Troubleshooting section
2. Search existing issues
3. Include Thunderbird version and extension version

---

🙏 Contributing

We welcome contributions! Here's how to help:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing)
5. 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:

• Google Gemini
• OpenAI
• Anthropic Claude
• Groq
• Mistral AI

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

---

Support This Project

Support this project! All donations go towards your chosen charity. You can pick any charity you'd like, and I will ensure the funds are sent their way. Please note that standard payment processing fees (Ko-fi & PayPal) will be deducted from the total. 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 of the donation or to let me know which charity you've selected!