🎯 InboxAI

AI-powered Gmail inbox organizer using LangGraph, LangChain, and Google's Gemini AI. Automatically classify, summarize, and manage your emails with intelligent workflows.

🌟 Features

• Intelligent Email Classification: Automatically categorizes emails into:

  • 📰 Informative (newsletters, updates, notifications)
  • 💬 Requires Reply (emails needing your response)
  • 🗑️ Ignored (spam, promotions, unimportant messages)

• AI-Powered Summarization:

  • Concise summaries of informative emails
  • Context extraction for emails requiring replies
  • Smart reply generation with multiple tone options

• LangGraph Workflow: State-machine orchestrated email processing pipeline

• Model Context Protocol (MCP) Server: Ready-to-use MCP server for AI assistant integration with Claude Desktop and other AI assistants

• Gmail API Integration: Full read/write access to your Gmail account

🏗️ Architecture

📧 InboxAI Workflow
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Fetch Emails  │───▶│ Classify Emails │───▶│   Summarize     │
│                 │    │                 │    │   Informative   │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                                │                        │
                                ▼                        ▼
                       ┌─────────────────┐    ┌─────────────────┐
                       │   Summarize     │───▶│  Present to     │
                       │ Requires Reply  │    │     User        │
                       └─────────────────┘    └─────────────────┘

🔧 Project Structure

InboxAI/
├── src/
│   ├── main.py                 # CLI interface and main entry point
│   ├── mcp_server.py           # Model Context Protocol server
│   ├── graph.py                # LangGraph workflow definition
│   └── tools/
│       ├── gmail.py            # Gmail API client and Email class
│       ├── summarise_email.py  # Email summarization functions
│       └── reply_email.py      # Email reply generation and sending
├── tests/
│   └── test_graph.py           # Comprehensive test suite
├── pyproject.toml              # Project configuration and dependencies
├── requirements.txt            # Legacy requirements file
└── README.md                   # This file

🚀 Quick Start

1. Prerequisites

• Python 3.12+
• Gmail account with API access
• Google Cloud Project with Gmail API enabled

2. Installation

# Clone the repository
git clone https://github.com/yourusername/InboxAI.git
cd InboxAI

# Install dependencies with uv (recommended)
uv sync

# Or install with pip
pip install -e .

3. Gmail API Setup

1. Create a Google Cloud Project:

   • Go to Google Cloud Console
   • Create a new project or select existing one

2. Enable Gmail API:

   • Navigate to "APIs & Services" > "Library"
   • Search for "Gmail API" and enable it

3. Create Credentials:

   • Go to "APIs & Services" > "Credentials"
   • Click "Create Credentials" > "OAuth 2.0 Client IDs"
   • Choose "Desktop Application"
   • Download the JSON file as credentials.json

4. Place Credentials:

   # Place the downloaded file in the project root
   cp ~/Downloads/credentials.json ./credentials.json

4. Environment Setup

Create a .env file in the project root:

# Google AI API Key (for Gemini)
GOOGLE_API_KEY=your_google_ai_api_key_here

# Optional: Customize LLM model
LLM_MODEL=google_genai:gemini-2.5-flash

5. First Run

# Run InboxAI
uv run python src/main.py

# Or specify time window
uv run python src/main.py --time 7d

# Interactive mode
uv run python src/main.py --interactive

📖 Usage

Command Line Interface

# Basic usage - process last 24 hours
uv run python src/main.py

# Specify time window
uv run python src/main.py --time 12h    # Last 12 hours
uv run python src/main.py --time 7d     # Last 7 days
uv run python src/main.py --time 3d     # Last 3 days

# Show processing statistics
uv run python src/main.py --stats --time 24h

# Reply to an email
uv run python src/main.py --reply email_id_123 --reply-text "Thanks for your message!"

# Generate reply suggestions
uv run python src/main.py --suggestions email_id_123

# Interactive mode
uv run python src/main.py --interactive

Interactive Mode Commands

📧 InboxAI> process 24h           # Process emails from last 24 hours
📧 InboxAI> stats 7d              # Show statistics for last 7 days
📧 InboxAI> reply 123 Thank you!  # Reply to email with ID 123
📧 InboxAI> suggest 123           # Get reply suggestions for email 123
📧 InboxAI> quit                  # Exit interactive mode

Python API

from src.graph import process_inbox
from src.tools.reply_email import reply_to_email_mcp
from src.tools.summarise_email import summarise_emails_mcp

# Process emails
result = process_inbox("24h")
print(result)

# Summarize emails using MCP function
summary = summarise_emails_mcp("24h")
print(summary)

# Reply to an email
reply_result = reply_to_email_mcp(
    email_id="123",
    reply_text="Thank you for your email!",
    auto_generate=False
)

# Auto-generate a reply
auto_reply = reply_to_email_mcp(
    email_id="123",
    auto_generate=True,
    tone="professional"
)

🔧 Configuration

Environment Variables

Variable	Description	Default
GOOGLE_API_KEY	Google AI API key for Gemini	Required
LLM_MODEL	Language model to use	google_genai:gemini-2.5-flash

Gmail API Scopes

The application requires these Gmail API scopes:

• https://www.googleapis.com/auth/gmail.readonly - Read emails
• https://www.googleapis.com/auth/gmail.send - Send emails
• https://www.googleapis.com/auth/gmail.modify - Modify emails

🧪 Testing

Run the test suite:

# Install test dependencies
uv add --dev pytest pytest-mock

# Run tests
uv run pytest tests/ -v

# Run with coverage
uv run pytest tests/ --cov=src --cov-report=html

Test Structure

• Unit Tests: Individual component testing
• Integration Tests: Complete workflow testing
• Mock Tests: Gmail API and LLM interaction testing
• Error Handling: Exception and edge case testing

🔌 MCP Integration

InboxAI provides a Model Context Protocol server for integration with AI assistants like Claude Desktop:

Available Tools

• summarise_emails_mcp(time_window) - Fetch and categorize emails with AI summaries
• reply_to_email_mcp(email_id, reply_text) - Send intelligent replies
• get_email_suggestions(email_id, num_suggestions) - Generate multiple reply options
• process_inbox_full(time_window) - Run complete workflow

Usage with Claude Desktop

# Start MCP server
uv run python src/mcp_server.py

See MCP_GUIDE.md for detailed integration instructions.

🎨 Customization

Adding New Email Categories

1. Update the EmailClassification model in graph.py:

   category: Literal["informative", "requires_reply", "ignored", "urgent"] = Field(...)

2. Modify classification logic in classify_emails_node()

3. Add corresponding summarization logic

Custom LLM Models

# In graph.py, change the LLM initialization
llm = init_chat_model("openai:gpt-4")  # Use OpenAI
llm = init_chat_model("anthropic:claude-3")  # Use Anthropic

🐛 Troubleshooting

Common Issues

1. "Import googleapiclient.discovery could not be resolved"

   uv add google-api-python-client google-auth-oauthlib

2. Gmail API Authentication Failed

   • Ensure credentials.json is in the correct location
   • Check that Gmail API is enabled in Google Cloud Console
   • Verify OAuth 2.0 client ID is configured for "Desktop Application"

3. "No module named 'google.generativeai'"

   uv add google-generativeai

4. Empty Email Results

   • Check Gmail API quotas and limits
   • Verify time window format (e.g., "24h", "7d")
   • Ensure you have unread emails in the specified timeframe

Debug Mode

Enable detailed logging:

export PYTHONPATH=$PYTHONPATH:./src
uv run python src/main.py --time 1h --verbose

🚧 Development

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make changes and add tests
4. Run tests: uv run pytest tests/
5. Submit a pull request

Development Setup

# Install development dependencies
uv sync --dev

# Install pre-commit hooks (optional)
pre-commit install

# Run linting
uv run flake8 src/ tests/
uv run black src/ tests/

# Type checking
uv run mypy src/

🏗️ Technical Architecture

LangGraph State Machine

The email processing workflow is implemented as a LangGraph state machine with the following nodes:

• Fetch Node: Retrieves emails from Gmail API with time filtering
• Classify Node: Uses Gemini AI to categorize emails into types
• Summarize Informative Node: Generates concise summaries for informative emails
• Summarize Reply Node: Extracts context and suggests replies for actionable emails
• Present Node: Formats and presents results to the user

AI Integration

• Classification: Uses structured output with Pydantic models for reliable categorization
• Summarization: Context-aware prompts optimized for different email types
• Reply Generation: Multi-tone reply suggestions with professional/casual/friendly options

Data Privacy

• All email processing happens locally
• Only email classification/summarization uses external AI API (Google Gemini)
• No email content is stored permanently
• OAuth credentials are securely managed

📄 License

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

🙏 Acknowledgments

• LangChain & LangGraph for the orchestration framework
• Google Gemini for AI capabilities
• Gmail API for email access
• Python ecosystem for excellent tooling

📞 Support

• 📖 Documentation
• 🔧 Setup Guide
• 🔌 MCP Integration
• 🐛 Issue Tracker

---

Built with ❤️ using LangGraph, LangChain, and Google AI

Designed for developers who want to leverage AI for intelligent email management.