Markdown

📬 Mail Automation (mail-auto)

A powerful, priority-based email policy engine and CLI toolkit for taking back control of your inbox.

Unlike simple "delete all" scripts, mail-auto acts as a local-first email management platform. It uses Gmail's native bulk-search API and a deterministic Set Math Engine to resolve rule conflicts, ensuring important emails are never accidentally deleted.

---

✨ Core Features

• 🛡️ Priority Engine: Define rules with strict priorities. (e.g., A priority: 100 rule to protect starred emails will mathematically override a priority: 60 rule to trash promotions).
• 🔒 Local-First Security: No data ever leaves your machine. The app communicates directly with Google's servers via OAuth 2.0.
• 🛑 Dry-Run by Default: The engine is inherently safe. It will generate a detailed execution plan and wait for the --execute flag before modifying a single email.
• 🔪 Unsubscribe Radar: Scans for newsletters and extracts hidden List-Unsubscribe web links, allowing you to bulk-unsubscribe directly in your browser.
• 📊 Interactive Analytics: Generates beautiful terminal dashboards of your inbox traffic, read-rates, and category breakdowns.
• 🏷️ Dynamic Labeling: Automatically creates and applies Gmail labels based on sender or subject rules.

---

🚀 Installation

1. Clone the repository

git clone [https://github.com/YOUR_USERNAME/mail-automation.git](https://github.com/YOUR_USERNAME/mail-automation.git)
cd mail-automation
2. Install the CLI
Install the package natively to register the mail-auto command on your system.

Bash
pip install -e .
3. Authenticate with Google
Go to the Google Cloud Console.

Create a new project and enable the Gmail API.

Create an OAuth 2.0 Client ID (Desktop Application).

Download the JSON file, rename it to credentials.json, and place it in the root folder of this project.

Run any command (e.g., mail-auto stats) to trigger the one-time browser login. This will generate a local token.json file.

⚙️ Configuration (config/rules.yaml)
Define your inbox policies in plain English using the YAML configuration file. The engine reads these rules, sorts them by priority, and executes them safely.

YAML
whitelist:
  - linkedin.com
  - github.com
  - google.com

rules:
  # --- PROTECTION RULES (Highest Priority) ---
  - name: "Protect Starred"
    priority: 100
    query: "is:starred"
    action: "SKIP"

  - name: "Protect Important"
    priority: 95
    query: "label:important"
    action: "SKIP"

  # --- CLEANUP RULES ---
  - name: "Trash Expired OTPs"
    priority: 80
    query: "subject:OTP older_than:7d"
    action: "TRASH"

  - name: "Archive Promotions"
    priority: 60
    query: "category:promotions in:inbox"
    action: "ARCHIVE"
    mark_read: true

  # --- ORGANIZATION RULES ---
  - name: "Label Finance"
    priority: 40
    query: "from:hdfcbank.com OR from:icicibank.com"
    action: "LABEL"
    label_name: "Finance"
Supported Actions: SKIP, ARCHIVE, TRASH, READ_ONLY, LABEL

🛠️ CLI Usage
The app features a beautiful terminal UI powered by Rich and Typer.

🔍 View Active Rules
See exactly how the engine is interpreting your rules.yaml file, sorted by priority.

Bash
mail-auto rules
🛡️ Scan & Execute (Dry-Run by Default)
Generate a safety report showing exactly how many emails will be affected by each rule.

Bash
mail-auto scan
When you are ready to actually move the emails, append the execute flag:

Bash
mail-auto scan --execute
📉 Inbox Analytics
View a high-level breakdown of your email traffic over the last X days.

Bash
mail-auto stats
mail-auto stats --days 30
🚫 Unsubscribe Radar
Find hidden unsubscribe links from the last X days of newsletters and optionally open them in your browser.

Bash
mail-auto unsubscribe
mail-auto unsubscribe --days 120
🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request. If you are adding a new core action to the engine, please ensure it supports the mark_read optional flag.

📜 License
This project is licensed under the MIT License - see the LICENSE file for details.