email-classifier/docs/index.md

email-classifier

FastAPI service that classifies emails using a configurable LLM backend. It accepts Outlook-shaped email JSON payloads, extracts structured classification data, and tracks duplicate classifications using a local SQLite dedupe store.

Purpose

This service is designed to help workflow systems (e.g., Todoist ticket creation) automatically process incoming emails by:

• Determining whether an email requires action
• Extracting priority, category, suggested task title/notes, people, organizations, and deadlines
• Deduplicating repeated emails based on Outlook message ID, conversation ID, or content fingerprinting

Key Features

• Configurable LLM providers — OpenAI-compatible (Ollama, LM Studio, OpenAI) or Anthropic-compatible (MiniMax, Anthropic API)
• Outlook-shaped input — Accepts native Microsoft Graph API email payloads with no transformation required
• Simplified input — Also accepts a minimal email_data shape with just subject and body
• Deduplication — Local SQLite store tracks seen emails by message ID, conversation ID, or content fingerprint
• Structured extraction — Returns classification, priority, suggested task title/notes, people, organizations, deadlines, and more

Project Structure

email-classifier/
├── app/
│   ├── main.py              # FastAPI app entry point
│   ├── config.py            # Pydantic settings from environment variables
│   ├── classifier.py        # Core classification orchestration
│   ├── llm_adapters.py       # OpenAI- and Anthropic-compatible adapter layer
│   ├── models.py            # Pydantic request/response models
│   ├── prompts.py           # System prompt sent to the LLM
│   ├── sync.py              # Deduplication logic and content fingerprinting
│   ├── dedupe_store.py      # SQLite persistence for dedupe tracking
│   ├── routers/
│   │   └── classify_email.py # /classify POST endpoint
│   └── helpers/
│       ├── clean_email_html.py
│       ├── extract_latest_message.py
│       └── remove_disclaimer.py
├── docs/                    # MkDocs documentation (this site)
├── Dockerfile
├── pyproject.toml
└── uv.lock

Output Classification Schema

Emails are classified into one of these categories:

Category	Description
action_required	Direct request requiring user action
question	Question needing a response
fyi	Informational, no reply needed
newsletter	Newsletter or publication
promotional	Marketing or sales outreach
automated	Automated system notification
alert	I.T. or security alert
uncategorized	Fallback when classification fails

Priority is one of: high, medium, low.