AI Email Assistant - Local Setup Guide

A local AI-powered email assistant that helps you manage, analyze, and respond to emails intelligently.

Features

• 📧 Connect to your email account (Gmail, Outlook, etc.)
• 🤖 AI-powered email analysis and categorization
• 📁 NEW! Automatic email categorization (Primary, Social, Promotions, Notifications)
• 📅 Date-based sub-categorization (Today, Yesterday, This Week, etc.)
• ✍️ Draft intelligent email responses
• 📊 Summarize long email threads
• 🔍 Smart email search and filtering
• 🔐 Fully local and private (your choice of AI backend)

Step-by-Step Setup

Step 1: Install Python Dependencies

First, install the required Python packages:

pip install -r requirements.txt

Step 2: Choose Your AI Backend

You have two options:

Option A: OpenAI API (Easiest, requires API key)

• Sign up at https://platform.openai.com/
• Get your API key
• Set it in .env file

Option B: Local LLM with Ollama (100% Free & Private)

1. Download Ollama from https://ollama.ai/
2. Install it on your system
3. Pull a model: ollama pull llama3.2
4. Set AI_PROVIDER=ollama in .env file

Step 3: Configure Your Email Account

Create a .env file in the root directory:

# AI Configuration
AI_PROVIDER=openai  # or 'ollama' for local
OPENAI_API_KEY=your-api-key-here  # Only needed if using OpenAI
OLLAMA_MODEL=llama3.2  # Only needed if using Ollama

# Email Configuration
EMAIL_ADDRESS=your.email@gmail.com
EMAIL_PASSWORD=your-app-specific-password

# For Gmail: Use App Password (not your regular password)
# Guide: https://support.google.com/accounts/answer/185833
IMAP_SERVER=imap.gmail.com
SMTP_SERVER=smtp.gmail.com
IMAP_PORT=993
SMTP_PORT=587

Step 4: Set Up Email Access

For Gmail:

1. Go to Google Account Settings
2. Enable 2-Factor Authentication
3. Generate an "App Password" at https://myaccount.google.com/apppasswords
4. Use this app password in your .env file

For Outlook/Microsoft 365:

• IMAP_SERVER: outlook.office365.com
• SMTP_SERVER: smtp.office365.com
• Use app password or OAuth (app password recommended)

Step 5: Run the Assistant

Option A: Command Line Interface (CLI)

python email_assistant.py

Option B: REST API Server (for frontend integration)

python api_routes.py

Or using uvicorn:

uvicorn api_routes:app --reload --host 0.0.0.0 --port 8000

Then access the interactive API documentation at: http://localhost:8000/docs

Usage Guide

"Hiring" Your AI Assistant

When you run the assistant for the first time, it will:

1. Connect to your email account
2. Load your recent emails
3. Introduce itself and ask how it can help

Communicating with Your Assistant

The assistant understands natural language commands:

📧 Email Management:
- "Show me unread emails from today"
- "Summarize my inbox"
- "Find emails from John about the project"
- "What are my important emails?"

📁 Smart Categories (NEW!):
- "categorize" - Organize all emails into categories
- "show categories" - View category overview
- "show primary" - View important work/personal emails
- "show social" - View social media notifications
- "show promotions" - View marketing emails
- "show notifications" - View system notifications
- "show primary today" - Filter by category and date

✍️ Writing Assistance:
- "Draft a reply to the latest email from Sarah"
- "Help me respond professionally to this complaint"
- "Write a follow-up email about the meeting"

📊 Analysis:
- "Summarize this email thread"
- "What's the sentiment of recent emails?"

⚙️ Commands:
- "help" - Show available commands
- "refresh" - Check for new emails
- "settings" - View current configuration
- "quit" - Exit the assistant

Project Structure

email-assistant/
├── email_assistant.py      # Main CLI application
├── api_routes.py          # FastAPI REST API server (NEW!)
├── ai_backend.py          # AI provider interface (OpenAI/Ollama)
├── email_handler.py       # Email operations (IMAP/SMTP)
├── email_categorizer.py   # Email categorization system
├── utils.py              # Helper functions
├── requirements.txt       # Python dependencies
├── .env                  # Configuration (create this)
├── README.md            # This file
├── API_DOCUMENTATION.md  # Complete API reference (NEW!)
├── API_QUICKSTART.md    # Quick start for frontend devs (NEW!)
├── CATEGORIES_GUIDE.md  # Detailed guide for email categories
└── .email_cache/        # Local cache for categorizations (auto-generated)

Security & Privacy

• ✅ All processing happens locally on your machine
• ✅ Email credentials stored only in local .env file
• ✅ Option to use fully local AI (Ollama) - no data sent to cloud
• ✅ No email content stored permanently
• ⚠️ Keep your .env file secure and never commit it to version control

Troubleshooting

"Authentication failed"

• Verify your email and app password are correct
• For Gmail, ensure you're using an App Password, not your regular password
• Check that IMAP is enabled in your email settings

"Connection refused"

• Verify IMAP_SERVER and ports are correct
• Check your firewall/antivirus settings
• Ensure you have internet connection

AI responses are slow

• If using OpenAI: Check your internet connection
• If using Ollama: Ensure Ollama is running (ollama serve)
• Try a smaller model (e.g., ollama pull llama3.2:3b)

Email Categorization

The assistant now includes an intelligent categorization system that organizes your emails:

Categories

• 📧 Primary: Important personal or work emails
• 👥 Social: Social media notifications and updates
• 🏷️ Promotions: Marketing emails and newsletters
• 🔔 Notifications: System notifications and receipts

Date Filters

• Today, Yesterday, This Week, This Month, Older

Quick Start

1. Run categorize to analyze your emails
2. Use show categories to see the overview
3. View specific categories: show primary, show social, etc.
4. Filter by date: show primary today, show social this week

For detailed information, see CATEGORIES_GUIDE.md

REST API for Frontend Integration

The assistant now includes a complete REST API for building web or mobile frontends!

Starting the API Server

python api_routes.py

API Features

• ✅ RESTful endpoints for all email operations
• ✅ Interactive documentation at http://localhost:8000/docs
• ✅ CORS enabled for frontend integration
• ✅ Pydantic validation for request/response
• ✅ Complete email management (fetch, categorize, search)
• ✅ AI features (summarize, draft replies, queries)

Quick API Test

// Fetch emails
const response = await fetch('http://localhost:8000/emails/fetch', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ criteria: 'UNSEEN', limit: 20 })
});
const data = await response.json();
console.log(`Fetched ${data.count} emails`);

Documentation for Developers

• API_DOCUMENTATION.md - Complete API reference with examples
• API_QUICKSTART.md - Quick start guide for frontend developers
• Postman Collection - Import and test all endpoints

Example Endpoints

• POST /emails/fetch - Fetch emails
• POST /emails/categorize - Categorize with AI
• GET /categories - Get category overview
• POST /categories/{category}/emails - View category
• POST /ai/summarize - Summarize emails
• POST /ai/draft-reply - Draft reply with AI
• POST /ai/search - Natural language search

Advanced Features

Custom Prompts

Edit the system prompts in ai_backend.py to customize your assistant's personality and behavior.

Email Filters

Create custom email filters in email_handler.py to automatically categorize or prioritize emails.

Scheduled Tasks

Use Windows Task Scheduler or cron to run the assistant periodically for automated email monitoring.

License

MIT License - Feel free to modify and use as you wish!

Contributing

Found a bug or want to add a feature? Contributions are welcome!