← Back to blog

Gmail Organiser: automatic email classification with LLMs

toolsllm

Email is a mess. Newsletters, receipts, notifications, and actual correspondence all mixed together. Gmail's built-in categories help, but they're coarse. I wanted something that would automatically sort emails into my own categories and archive the noise.

Gmail Organiser is an LLM-powered tool that classifies emails and applies Gmail labels. It's stateless and runs incrementally, processing only unclassified emails.

How it works

  1. Queries Gmail for emails missing category labels
  2. Sends batches to an LLM for classification
  3. Applies the corresponding Gmail label
  4. Archives noise categories (junk, newsletters, purchase confirmations, event invites) out of the inbox

The tool is stateless. It doesn't maintain a local database of processed emails. Instead, it uses the presence of category labels to determine what's been classified. This means you can run it repeatedly without duplicating work.

Configurable taxonomy

Categories are defined in a YAML file:

categories:
  - name: junk
    description: spam, scams, marketing, promotions
    archive: true
  - name: newsletter
    description: email newsletters and digests
    archive: true
  - name: work
    description: work-related correspondence
    archive: false

Each category becomes a Gmail label. Set archive: true to automatically remove from inbox.

Usage

# One-time OAuth setup
uv run python main.py auth

# Classify emails
uv run python main.py run

Safe to run on a schedule. It only processes emails that don't yet have a category label.

Links