nothx

nothx (no thanks) separates legitimate subscriptions from spam and phishing, then takes the safe action: unsubscribe from authenticated lists or suppress dangerous mail in Junk without contacting its sender. Mailbox access and body inspection stay on your machine. If you enable a cloud AI provider, only a bounded summary of locally selected marketing/spam headers is sent for preference classification—never message bodies or unrelated personal mail.

Your inbox, uncrowded.

Quick Start

pipx install nothx
nothx init

That's it. The wizard handles everything else.

Don't have pipx? brew install pipx (macOS) or sudo apt install pipx (Linux).

Run nothx anytime for the interactive menu.

Why nothx?

Features

Core

• AI-Powered — Claude, GPT, Gemini, or local models via Ollama
• Authenticated Unsubscribe — strict RFC 8058 one-click, vetted HTTPS GET, or constrained mailto
• Real Spam Suppression — consumes provider Junk/phishing verdicts and safely moves exact IMAP UIDs to the discovered Junk mailbox
• Privacy First — header-only by default; the optional footer scanner is local, bounded, and never sends footer content to AI

Smart

• Learns From You — Gets smarter every time you disagree with a decision
• 5-Layer Classification — Rules → Patterns → AI → Heuristics → Manual review
• Guarded Automation — unknown authentication, conflicting verdicts, and protected identities go to review

Practical

• Multi-Account — Scan Gmail + Outlook simultaneously
• Native Scheduling — No daemon needed. Uses launchd (macOS) or systemd (Linux).
• Future Policy Corrections — nothx undo domain.com changes nothx's future decision; it cannot externally resubscribe you

Beautiful

• Rich CLI — Animated banner, progress bars, colored output
• Interactive Mode — Just run nothx for menu-driven operation

The Learning System

nothx gets smarter the more you use it. Every decision trains your personal preference model.

What it learns:

• Keywords — Keep emails with "receipt"? Future receipt-related senders score safer.
• Open rates — If you keep emails you never open, it stops penalizing low engagement.
• Volume tolerance — Keep high-volume senders? It raises the threshold before flagging.

Corrections teach it too. When you run nothx undo, it doesn't just restore — it learns that this type of email matters to you.

nothx status --learning   # See your learned preferences

How It Works

Email arrives in Inbox or Junk
      ↓
┌─────────────────┐
│ PROVIDER POLICY │  Junk, phishing, authentication, mailbox flags
└────────┬────────┘
         ↓
┌─────────────────┐
│  USER RULES     │  Your exact keep, unsubscribe, and block choices
└────────┬────────┘
         ↓
┌─────────────────┐
│ LOCAL CANDIDATE │  List/bulk, engagement, and cold-outreach evidence
└────────┬────────┘
         ↓
┌─────────────────┐
│ AI / HEURISTICS │  Preference classification for selected candidates
└────────┬────────┘
         ↓
┌─────────────────┐
│ SAFE DISPOSITION│  Keep, review, unsubscribe, or move to Junk
└─────────────────┘

Provider threat evidence and explicit block rules are resolved before AI. Bulk mail is not automatically spam, and an unsubscribe link is not automatically safe.

Commands

Essentials

Day-to-Day

Configuration

Aliases: r (run), s (status), rv (review), h (history)

Setup

Requirements

• Python 3.11+
• Gmail, Outlook, Yahoo, or iCloud account
• AI provider (optional — works without AI too)

Installation

pipx is the recommended way to install nothx. It handles virtual environments automatically.

# Base install (heuristics only, or Ollama)
pipx install nothx

# With your preferred AI provider
pipx install "nothx[anthropic]"  # Claude (recommended)
pipx install "nothx[openai]"     # GPT-4
pipx install "nothx[gemini]"     # Google Gemini
pipx install "nothx[all-ai]"     # All providers

brew install pipx

# Ubuntu/Debian
sudo apt install pipx

# Fedora
sudo dnf install pipx

python3 -m venv ~/.nothx-venv
source ~/.nothx-venv/bin/activate
pip install nothx

Safety and privacy defaults

• Inbox and the unambiguously advertised IMAP \Junk mailbox are scanned. nothx does not guess localized Junk folder names; configure an override if your server advertises none or several.
• Initial runs use the configured lookback. Later runs use (account, mailbox, UIDVALIDITY, UID) cursors. Full history is always explicit.
• Body fetching is disabled by default. The optional footer scanner examines at most two inline text tails (64 KiB each, 128 KiB total) for authenticated list/bulk candidates. It skips attachments, nested messages, images, scripts, and forms.
• One-click POST requires compliant headers plus $canunsubscribe or a correlated passing DKIM signature that covers both unsubscribe headers. All outbound unsubscribe contact—including an explicitly opened browser page—and mailbox actions require separate, versioned consent.
• HTTP requests are HTTPS-only, proxy/cookie/auth/referrer-free, redirect constrained, SSRF checked, and connected to an already validated public IP while preserving TLS hostname verification.
• Stored targets are fingerprints and hashed destination labels. Complete hosts, paths, queries, mailto recipients/bodies, and HTTP response bodies are excluded from normal history and exports.

What an outcome means

• requested: the endpoint accepted a one-click/GET request, or SMTP accepted the mail for delivery. It does not guarantee mail will stop.
• needs_user: safe automation reached a login, form, JavaScript flow, preference center, CAPTCHA, or another manual boundary.
• verified_quiet: a complete post-grace scan found no later matching delivery.
• ineffective: matching mail arrived after the 48-hour grace period. One fresh-token or alternate-method retry is allowed; another post-grace delivery is blocked.
• blocked: nothx sent no unsubscribe traffic and applied its local spam path. Portable IMAP Junk movement is best effort; provider-side spam training is not guaranteed.

Troubleshooting

nothx reset              # Delete everything
nothx reset --keep-config # Keep accounts, clear history

Comparison

Philosophy

We built nothx because:

1. Your email is yours. Not a product to sell.
2. AI should adapt to you. Not the other way around.
3. Automation should be invisible. Set once, forget forever.
4. Words matter. A request is not verified cessation, and changing local policy cannot externally resubscribe an address.

Contributing

git clone https://github.com/sainihas/nothx.git
cd nothx
pip install -e ".[dev]"
pytest

License

MIT — see LICENSE

nothx — Because your inbox should work for you, not against you.

Made with mass frustration at marketing emails.