Applying consistent organisation to a long-running inbox is difficult when senders and message types have accumulated over time. This project explores how automation can assist with that review.
The pipeline fetches message metadata, groups senders, uses an LLM to suggest classifications, produces Gmail filter rules, and can apply labels to existing mail. Classifications should be reviewed before broad changes are applied.
fetch.py downloads each message’s From, Subject, and List-Unsubscribe headers with parallel workers, writing to a .jsonl file so the process can be resumed. Runtime will vary with mailbox size and API conditions.
python -m gmail_organizer.fetchthread_builder.py groups fetched messages into threads, collecting unique subjects and body samples per sender. thread_clusterer.py then groups those threads by domain using token-based subject keys, so all the receipts from noreply@shopify.com end up in one cluster, separate from their shipping notifications, rather than being treated as a single flat blob.
python -m gmail_organizer.thread_builder
python -m gmail_organizer.thread_clustererAn optional embedding_cluster_refiner step runs after clustering to further split or merge clusters using semantic embeddings, useful for high-volume senders that send genuinely different types of email from the same address.
cluster_classifier.py sends each cluster to an LLM with the sender domain, representative subjects, and any body samples collected during threading. The model returns a label, a tier, and any subject patterns needed to distinguish this cluster from others on the same domain. Results are cached per cluster so re-runs only hit the API for new or changed senders.
python -m gmail_organizer.cluster_classifierThe four tiers control what Gmail does with matched messages:
rule_builder.py merges classified clusters by (sender_domain, label) into a clean filter_rules.json, adding a gmail_query field for each rule. gmail_filter_export.py converts that into Gmail's XML import format.
python -m gmail_organizer.rule_builder
python -m gmail_organizer.gmail_filter_exportgmail_backfill.py applies labels thread-wise to everything that already exists using the Gmail API's batchModify endpoint, 1,000 messages per batch. Fifty thousand messages takes about two minutes.
python -m gmail_organizer.gmail_backfill --dry-run # preview
python -m gmail_organizer.gmail_backfill # applyThe pipeline stores the metadata needed for its workflow. Review the implementation and privacy implications before using it with a mailbox containing sensitive information.