AutoUnsub

A python tool that scans your Gmail inbox for senders with unsubscribe options and lets you unsubscribe from them without opening a bunch of emails yourself.

Overview

I made AutoUnsub because my inbox was getting kinda stupid with newsletters, random notifications, and stuff I signed up for once and completely forgot about.

Unsubscribing isn't really hard, but doing it over and over again is annoying, so I wanted to automate that part.

It uses Gmail IMAP to scan message headers and a small parser to figure out what unsubscribe option an email has. SQLite keeps track of the senders and messages so the same stuff doesn't keep getting counted.

I also didn't want to put everything into one massive Python file, so main.py is the only thing you actually run and everything else is split into smaller files.

Features

How It Works

Gmail -> IMAP -> parser -> SQLite -> terminal -> unsubscribe

The scanner only gets the headers it actually needs instead of downloading the whole email.

Then it pulls out the sender, date, and unsubscribe info and sends that into the parser.

The results get stored in SQLite so AutoUnsub remembers what it has already seen.

When you unsubscribe, it uses whatever method was found in the email.

One-click options use a POST request, normal links use an HTTP request, and mailto: options get turned into an email and sent through Gmail SMTP.

Project Structure

Install

From PyPI

Once released, the normal user install will be:

python -m pip install auto-unsub
auto-unsub

This installs AutoUnsub as a real command-line application, so users do not need to clone the repository.

From source

For development:

python -m pip install -e .
auto-unsub

Development setup

It is recommended to use a virtual environment so the dependencies don't pollute your global Python installation:

python -m venv .venv
source .venv/bin/activate

On Windows:

python -m venv .venv
.venv\Scripts\activate

Then install the project:

python -m pip install -e .

Using AutoUnsub

On the first run it asks for your Gmail address and app password.

The app password gets stored using the system keyring so you don't have to enter it every time.

You do have to create the app password yourself from your Google account first.

After that you choose how many days back you want to scan and how many messages you want to check.

Then it shows you what it found.

What I Learned

Honestly this taught me way more than I expected.

I learned how Gmail IMAP works, how email headers are structured, and how unsubscribe headers can have a bunch of different formats.

I also got way more comfortable with SQLite and keeping state between runs.

The networking part was kinda interesting too because fetching messages one by one was ridiculously slow, so I changed it to fetch them in batches (default 25, but I can change this).

Real email data was also way messier than the fake tests I started with because some emails have no unsubscribe options at all and some have huge weird unsubscribe URLs.

Why I Built It

Mostly because I wanted it for myself.

My inbox has a bunch of random stuff that I don't really care about anymore, and manually cleaning it up is just boring and repetitive.

Current Status

The main thing works now.

AutoUnsub can connect to Gmail, scan real messages, figure out which ones have unsubscribe options, save everything to SQLite, and actually send unsubscribe requests.

The interface is still pretty basic and there's still a lot I want to improve, mainly making the scanning less slow, handling weird unsubscribe services better, and making the whole thing feel like an actual finished app.