AI-Driven Email Assistant

⚠️ NOTE:- This project is in under development and is not yet production-ready. If you want to know the Email processing pipeline with AI Agent then navigate to temp folder and check out the temp/main.py file. It contains the main entry point for the application and orchestrates the email processing workflow.

An AI-powered email automation system that fetches, filters, summarizes, and generates responses to emails using advanced language models. It integrates with both IMAP and SMTP servers and utilizes a state-graph workflow to manage email processing.

Table of Contents

• AI-Driven Email Assistant
  • Table of Contents
  • Overview
  • Features
  • Sequence Diagram
  • Installation
    • Prerequisites
    • Setup
  • Configuration
  • Usage
    • What to Expect
  • Directory Structure of temp folder

Overview

This repository implements an email processing pipeline that leverages state-of-the-art language models (via Openai API) and a state graph workflow (using LangGraph) to:

• Ingest Emails: Fetch emails from an IMAP server or load simulated emails from a JSON file.
• Filter Emails: Classify incoming emails as spam, urgent, informational, or needs review.
• Summarize Emails: Generate concise summaries of email content.
• Generate Responses: Automatically draft email replies while allowing human review.
• Send Emails: Dispatch responses via SMTP or send drafts to a Gmail account.

Features

• Email Ingestion: Supports both live email fetching (via IMAP) and simulation (via a local JSON file).
• Filtering Agent: Uses a language model to classify emails into categories.
• Summarization Agent: Generates 2–3 sentence summaries of email bodies.
• Response Agent: Drafts polite and professional responses based on email content and summaries.
• Human Review: Provides an option for manual review and editing of auto-generated responses.
• State Graph Workflow: Orchestrates the email processing steps (filtering, summarization, and response generation) with conditional transitions.
• Logging: Detailed logging for debugging and monitoring application behavior.

Sequence Diagram

Sequence Diagram

Installation

Prerequisites

• Python 3.8 or above
• pip
• (Optional) virtualenv

Setup

1. Clone the repository:

   git clone https://github.com/sayandedotcom/inbox-ai.git
   cd inbox-ai

2. Create and activate a virtual environment (recommended):

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install the dependencies:

   pip install -r requirements.txt

Configuration

The application requires several configuration settings (such as API keys and email server credentials). Create a .env file in the project root with the following variables:

To get SMTP Settings: You can use the Gmail SMTP server. I suggest you use an email you don’t use for personal use. Any gmail that has less mails in inbox ( for faster gmail processing ). The first thing we need is to set up 2-factor verification. Go to the https://myaccount.google.com/security and allow it on your account. As a second step, we need to create an app. Go to https://myaccount.google.com/apppasswords. It will give you a password, which we will use in this application.

# Openai API
OPENAI_API_KEY=your_openai_api_key

# SMTP Settings
EMAIL_SERVER=smtp.yourserver.com
EMAIL_USERNAME=[email protected]
EMAIL_PASSWORD=your_email_password
EMAIL_PORT=587  # Or your SMTP port

# IMAP Settings (defaults to Gmail settings if not provided)
IMAP_USERNAME=your_imap_username
IMAP_PASSWORD=your_imap_password
IMAP_SERVER=imap.gmail.com
IMAP_PORT=993

Adjust the values as needed for your environment and email provider.

Usage

To run the main email processing application, simply execute:

python main.py

What to Expect

1. Fetching Emails:
   The app will retrieve emails from your IMAP server (or simulate using sample_emails.json if configured for simulation).

2. Email Processing:
   Each email is passed through a state graph workflow:

   • Filtering: Classifies the email (e.g., spam, urgent, informational, needs review).
   • Summarization: Generates a short summary of the email content.
   • Response Generation: Drafts a reply. If the response is uncertain or flagged for review, it prompts for human intervention.

3. Sending/Drafting:
   You’ll be prompted to send the email or save it as a draft (which will be sent via SMTP to your specified Gmail address).

Directory Structure of temp folder

.
├── agents
│   ├── filtering_agent.py           # Email classification using LLMs
│   ├── human_review_agent.py        # Allows manual review of generated responses
│   ├── response_agent.py            # Generates email replies
│   ├── summarization_agent.py       # Summarizes email content
│   └── __init__.py
├── config.py                        # Loads configuration and environment variables
├── core
│   ├── email_imap.py                # IMAP integration for fetching live emails
│   ├── email_sender.py              # SMTP integration for sending emails
│   ├── state.py                     # Definition of the EmailState dataclass
│   ├── supervisor.py                # Coordinates the state graph workflow
│   └── __init__.py
├── main.py                        # Main entry point for the application
├── README.md                      # This documentation file
├── requirements.txt               # Python dependencies
└── utils
    ├── formatter.py               # Utility functions for formatting emails
    ├── logger.py                  # Logger configuration and setup
    └── __init__.py