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.

```json
{
  "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.

```json
{
  "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):**
```bash
python3 -m venv venv
```

**Activate the environment and install packages:**
(Activate the environment every time you open a new terminal)
```bash
source venv/bin/activate
pip install -r requirements.txt
```

### 4. Running the Web Server

With the virtual environment activated, run the FastAPI server:

```bash
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
```bash
docker build -t mail-manager .
```

### 2. Run the Container
```bash
# 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.