gmailextract

Gmail cleanup tool that extracts old emails with large attachments before deleting them, so nothing is lost.

What it does

Phase 1 — scans Gmail for emails older than N years (default: 5) with attachments, saves each as a .eml file alongside its extracted attachments, organised by year. Generates a CSV report of everything found.

Phase 2 — after you've verified the exports and uploaded them somewhere safe, moves those emails to Gmail Trash.

Quick start

# Requires: Python 3.10+, Gmail IMAP enabled, and an App Password
# https://myaccount.google.com/apppasswords

export GMAIL_USER="you@gmail.com"
export GMAIL_APP_PASSWORD="xxxx xxxx xxxx xxxx"

python3 gmail_extract.py --dry-run   # preview scope
python3 gmail_extract.py             # extract
# → review output/extraction_report.csv
python3 gmail_trash.py --dry-run     # verify count
python3 gmail_trash.py               # move to Trash

See SETUP.md for full instructions including how to enable IMAP and create an App Password.

Key flags

Flag	Default	Effect
--dry-run	off	Scan only, write nothing
--years N	5	Only emails older than N years
--min-kb N	500	Minimum message size in KB
--limit N	unlimited	Cap for testing