📬 Gmail Organizer

Your inbox, filed and archived — automatically. Rules first, AI only for what's left, and it never reads your email bodies.

Gmail Organizer tames a messy inbox with three passes:

1. Labels — rule-based by sender/domain (instant, free, offline)
2. Archive — moves old labeled mail out of the Inbox (kept in All Mail)
3. Trash — bins senders you never want to hear from again
4. AI — classifies whatever the rules missed, reading only the sender and subject line — never the body

The result: your Inbox only shows what needs you — everything else is filed under its label, and nothing is ever deleted unless a rule says so.

• Reads sender + subject only. Message bodies are never fetched or sent anywhere.
• AI runs locally by default (Ollama) — zero data leaves your machine. A Google Gemini option exists if you want it.
• Everything happens inside your own Gmail account via the official Gmail API.

# 1. Install dependencies
pip install google-api-python-client google-auth-oauthlib google-auth pyyaml
#    (Ollama users: install + run Ollama, then pull a model, e.g. llama3.2)

# 2. Enable the Gmail API for your Google account
#    https://console.cloud.google.com → New Project → APIs & Services
#    → Enable "Gmail API" → Credentials → OAuth 2.0 Client ID → Desktop app
#    → Download JSON → save to ~/.config/gmail-organizer/credentials.json

# 3. First run — opens a browser to authorize once
python3 gmail-organizer.py --dry-run

The first run creates a sample rules.yaml at ~/.config/gmail-organizer/rules.yaml — edit the senders and labels to match your inbox, then re-run.

# ~/.config/systemd/user/gmail-organizer.service
[Unit]
Description=Gmail Organizer

[Service]
Type=oneshot
ExecStart=/usr/bin/python3 /home/you/gmail-organizer.py --dry-run   # ← remove --dry-run when happy

[Install]
WantedBy=default.target

# ~/.config/systemd/user/gmail-organizer.timer
[Timer]
OnCalendar=*-*-* 08:00,13:00,20:00:00
Persistent=true

[Install]
WantedBy=timers.target

systemctl --user enable --now gmail-organizer.timer

MIT — free, open source, do whatever you want with it. A star is appreciated ⭐

Part of the CyberGlobal tiny-tools series — small, useful, privacy-first software. (See also sweep-lite.)