← Back to Projects

Email Tracker

Gmail issue tracker that fetches unread threads, classifies them into categories, summarizes conversations, and stores results in Supabase and Excel for easy tracking.

Python
View Source

Email Issue Tracker (LangGraph + Gmail Threads)

This project fetches unread Gmail threads, filters by a group email identifier in the To field, classifies issues, and summarizes both the entire thread and the latest message. Results are stored in Supabase and an Excel workbook.

Key features

  • Uses Gmail IMAP threads (X-GM-THRID) to fetch complete threads from newest to oldest.
  • Filters to threads where the To contains GROUP_EMAIL_IDENTIFIER.
  • LangGraph pipeline summarizes the whole thread and the newest message and classifies:
    • Category: Tech, Finance, Operations, Supply Chain, Business, Retail, Analytics, Product
    • Status: Done, In Process, Pipeline
    • Also returns relevance and group_id.
  • Stores to Supabase and issue_tracker.xlsx with a link to the latest message.

Setup

  1. Install dependencies (uses pyproject.toml):
python3 -m pip install -U pip
pip install -e .

  1. Enable Gmail IMAP and create an App Password for your account.

  2. Create a .env file:

IMAP_SERVER=imap.gmail.com
EMAIL_USER=your_email@gmail.com
APP_PASSWORD=your_app_password
GEMINI_API_KEY=your_gemini_api_key
SUPABASE_URL=your_supabase_url
SUPABASE_KEY=your_supabase_service_key
GROUP_EMAIL_IDENTIFIER=group@yourdomain.com

Notes:

  • Threads use the Gmail IMAP extension X-GM-EXT-1. If unavailable, the script falls back to single-email processing.
  • The Excel file now includes a LatestLink column.

Run

python3 main.py

Or with uv (recommended fast runner):

uv run main.py

Supabase is optional; if SUPABASE_URL and SUPABASE_KEY are not set, the app will operate in Excel-only mode.

Data columns (Excel)

  • IssueID, Summary, Category, Status, From, Date, ThreadID, History, LatestLink

Classification context used

Issues

  • Tech – App/website bugs, downtime, security, payment errors.
  • Finance – Billing, refunds, vendor payments, compliance.
  • Operations – Order delays, warehouse, workforce, processes.
  • Supply Chain – Procurement, inventory, logistics, disruptions.
  • Business – Strategy, partnerships, competition, growth.
  • Retail – Store issues, stock gaps, POS, customer experience.
  • Analytics – Data errors, KPI tracking, reporting, insights.
  • Product – Quality, packaging, formulations, customer feedback.

Classifier

  • relevance + Group Id

Status

  • Done
  • In Process - currently working on it
  • Pipeline - we will work in future

History

  • latest email summary