Mail-Agent — AI Email Categorizer

An autonomous personal Python agent that analyzes job application and interview emails in your Gmail inbox, automatically categorizing and labeling them into 4 main categories.

---

Features

• Fetches the latest email from the inbox (Sender, Subject, Snippet).
• Analyzes the content using OpenAI's gpt-4o-mini model.
• Classifies emails into one of 4 categories:
  • acceptance: Positive application/interview outcome.
  • rejection: Negative application/interview outcome.
  • sponsor: Job postings, account activations, automated/system notifications.
  • other: None of the above.
• Automatically creates (if missing) and applies AI/Acceptance, AI/Rejection, AI/Sponsor, or AI/Other labels in Gmail.

---

How It Works

flowchart LR
    subgraph Auth & Read
        A["credentials.json"] -->|OAuth2| B["auth.py<br/>(Gmail Service)"]
        B --> C["read.py<br/>(Fetch Latest Mail)"]
    end
    subgraph Classify & Tag
        C -->|Sender, Subject, Snippet| D["OpenAI API<br/>(gpt-4o-mini)"]
        D -->|Category| E["classify.py<br/>(Label Logic)"]
        E -->|Create/Apply Label| F["Gmail Inbox"]
    end

Loading

1. Authentication (auth.py)

Uses an OAuth 2.0 Desktop App credential from the Google Cloud Console. It initiates a browser-based authorization flow on the first run and saves a token.json for subsequent sessions. Operates securely with the gmail.modify scope (read and label only; no deletion rights).

2. Email Reading (read.py)

Utilizes the Gmail API to fetch the most recent message (maxResults=1). It extracts the sender and subject from the headers, alongside the email snippet, returning the data as a structured dictionary.

3. Classification & Labeling (classify.py)

Sends the parsed email data to the OpenAI API via a customized prompt. The model classifies the email, respecting specific edge cases (e.g., explicitly marking activation/welcome emails as sponsor, not acceptance). Once the decision is made, the corresponding label is applied to the email via the Gmail API.

---

Project Structure

.
├── auth.py             # Handles Gmail OAuth 2.0 flow and builds the service object
├── read.py             # Fetches and parses the latest email from Gmail
├── classify.py         # Main agent. Coordinates reading, LLM classification, and labeling
├── credentials.json    # OAuth 2.0 Client ID file (downloaded from Google Cloud)
├── token.json          # Generated automatically after first successful login
├── .env                # Environment variables (API keys, etc.)
├── .gitignore          # Isolates sensitive files (.env, *.json, venv, etc.) from git
└── requirements.txt    # Project dependencies

---

Setup & Execution

1. Install dependencies:

   pip install -r requirements.txt

2. Configure API credentials:

   • Create a .env file in the root directory and add your OpenAI API key:

     OPENAI_API_KEY=sk-proj-...

   • Download your OAuth 2.0 Client ID file from Google Cloud Console and save it to the root directory as credentials.json.

3. Run the agent:

   python classify.py

   (To test email fetching without triggering the OpenAI API, you can run python read.py.)