ai-mail-server/README.md

AI-Powered Mail Automation Engine

This project provides a framework for automatically processing emails from an IMAP server based on a user-defined set of rules. It can categorize, archive, or delete emails, serving as a powerful personal email assistant.

Core Concepts

The engine works by connecting to an IMAP mail server, fetching unread emails, and processing them according to rules you define in a JSON file. This allows for a highly customizable workflow to manage your inbox.

AI-Powered Classification

The standout feature is the ability to use Google's Gemini large language model to classify emails based on their content. You define a list of categories, and the AI will determine the most appropriate one for each email. This allows for much more intelligent and nuanced routing than simple keyword matching.

Key Components

• main.py: The main entry point that runs the FastAPI web server and provides the API.
• processing_logic.py: The core module that handles the email processing workflow, including the rule engine.
• ai_classifier.py: The module that communicates with the Gemini API to classify emails.
• imap_client.py: A class that handles all communication with the IMAP server.
• config.json: Stores your sensitive connection details and API keys.
• rules.json: This is where you define your workflow. You create rules that match email properties (like sender or subject) or AI classification results, and link them to specific actions.
• web/: Contains the HTML, CSS, and JavaScript files for the web UI.

The 4-Step Workflow

Based on the rules you set, the script can perform one of the following actions for each email:

1. DEVONthink (Archive): Downloads the email as a .eml file and saves it to a specified folder. This folder can be indexed by DEVONthink for automatic import.
2. CATEGORIZE: Moves the email to a specific mailbox on the server.
3. REVIEW: Moves the email to a "Review" mailbox if it doesn't match any other rule, allowing you to handle it manually.
4. TRASH: Moves the email to the Trash.

Setup and Usage (Local Development)

1. Configure Credentials (config.json)

Update config.json with your mail server details and your Gemini API key.

{
  "username": "your_email_username",
  "password": "your_email_password",
  "imap": {
    "server": "mail.hyungi.net",
    "port": 993
  },
  "gemini_api_key": "YOUR_GEMINI_API_KEY"
}

• You can get a Gemini API key from Google AI Studio.

2. Define Your Workflow (rules.json)

This is the most important step. Open rules.json and define your email processing logic.

To use the AI, first define your categories in the ai_categories list. Then, create rules that use the ai_classification_is condition.

{
  "ai_categories": ["청구서", "프로젝트 업데이트", "광고", "개인 용무", "기타"],
  "rules": [
    {
      "rule_name": "AI 분류: 청구서는 DEVONthink로",
      "conditions": {
        "ai_classification_is": "청구서"
      },
      "action": {
        "type": "DEVONTHINK",
        "parameters": {
          "devonthink_inbox_path": "/path/on/nas/for/devonthink"
        }
      }
    },
    {
      "rule_name": "키워드: 중요한 프로젝트",
      "conditions": {
        "subject_contains": "[Urgent Project]"
      },
      "action": {
        "type": "CATEGORIZE",
        "parameters": {
          "move_to_mailbox": "INBOX/Urgent"
        }
      }
    }
  ],
  "default_action": {
    "type": "REVIEW",
    "parameters": {
      "move_to_mailbox": "INBOX/Review"
    }
  }
}

• ai_categories: A list of categories you want the AI to use.
• conditions: Can be subject_contains, from_contains, or ai_classification_is.
• action: The action to perform (DEVONTHINK, CATEGORIZE, TRASH, REVIEW).

3. Installation

This project uses a virtual environment to manage dependencies.

Create the environment (only once):

python3 -m venv venv

Activate the environment and install packages: (Activate the environment every time you open a new terminal)

source venv/bin/activate
pip install -r requirements.txt

4. Running the Web Server

With the virtual environment activated, run the FastAPI server:

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

• The --reload flag automatically restarts the server when you make code changes.
• Access the web UI by opening http://localhost:8000 in your browser.

Docker

You can also build and run this application as a Docker container.

1. Build the Image

docker build -t mail-manager .

2. Run the Container

# Make sure your config.json and rules.json are correctly filled out
docker run --rm -p 8000:8000 -v $(pwd)/config.json:/app/config.json -v $(pwd)/rules.json:/app/rules.json mail-manager

• -p 8000:8000: This maps port 8000 on your local machine to port 8000 in the container, making the web UI accessible at http://localhost:8000.
• -v: Using volumes mounts your local configuration files into the container, making it easy to manage them without rebuilding the image.

Roadmap

• Advanced Rule Conditions: Add more complex conditions to the rule engine (e.g., regex matching, checking for attachments).
• Improved Web UI: Enhance the web interface for a more user-friendly rule editing experience (e.g., with forms instead of raw JSON).
• Scheduler: Implement a scheduler within the application to run the email processing task automatically at regular intervals.