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
| Feature | |
|---|---|
| Scan Gmail from however many days back you want | |
| Set a max number of messages to scan | |
| Detect one-click unsubscribe options | |
| Detect normal HTTP and HTTPS unsubscribe links | |
Detect mailto: unsubscribe links |
|
| Store senders and message data in SQLite | |
| Don't count the same message twice | |
| Show message counts for each sender | |
| Show unsubscribe methods | |
| Unsubscribe from one sender | |
| Unsubscribe from multiple senders | |
| Track successful and failed attempts | |
| Store the Gmail app password using the system keyring | |
| Colored terminal interface |
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
| Path | Contents |
|---|---|
main.py |
the thing you actually run |
sweeper/config.py |
handles Gmail credentials |
sweeper/db.py |
DB |
sweeper/imap_scan.py |
scans Gmail |
sweeper/sweep.py |
connects the scanner, parser and database |
sweeper/unsub_parse.py |
figures out unsubscribe methods |
sweeper/unsubscribe.py |
actually sends the unsubscribe request |
tests/ |
tests for everything |
requirements.txt |
Python dependencies |
README.md |
this file |
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.
Metadata
Release files for auto-unsub 1.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| auto_unsub-1.0.0.tar.gz | 13.6 kB | With provenance | Details for auto_unsub-1.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| auto_unsub-1.0.0-py3-none-any.whl | Python 3 | none | any | Details for auto_unsub-1.0.0-py3-none-any.whl |
Total release size: 27.0 kB
Release files / auto_unsub-1.0.0.tar.gz
| Download URL | auto_unsub-1.0.0.tar.gz |
|---|---|
| Size | 13.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
38522457cff275f04bbf0af3a3eb9016adbed350717739b5b7988074b35c6e32
|
|
BLAKE2b-256 checksum How to use checksums |
875886623acbad3581f06da5227649eda8d25cc5086e7e3472e0087d2cdab762
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 6, 2026.
Transparency logRelease files / auto_unsub-1.0.0-py3-none-any.whl
| Download URL | auto_unsub-1.0.0-py3-none-any.whl |
|---|---|
| Size | 13.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
cd7e887224eed05cc5cfe5cc6911c084f62bc012b1ae28b860941852dffd9bb8
|
|
BLAKE2b-256 checksum How to use checksums |
aacfd45d531058f6ed8383a942e6d53001d782c04c73aab67f7f15e220a0d45e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 6, 2026.
Transparency logSecurity for auto-unsub 1.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for auto_unsub-1.0.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 6, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.