An Email Unsubscriber CLI

UnsubscribeMail is one of my earlier utility projects — a small Python command-line tool that tackles a very ordinary annoyance: the slow drip of marketing emails you never meant to sign up for, each with an "unsubscribe" link buried at the bottom. Instead of hunting them down one by one, I wanted a script that would find them all and let me deal with them in one pass.

Why I made it

Unsubscribing manually is death by a thousand clicks. But the pattern is completely mechanical — search your inbox, find the unsubscribe links, click them. Anything that mechanical is a candidate for automation, and it was a nice excuse to poke at how email actually works under the hood over IMAP.

How it was built

It's plain Python, and the flow is small enough to hold in your head:

• Connect to Gmail over IMAP with IMAPClient, using an app password.
• Run a Gmail search for the word "unsubscribe" to pull only the relevant messages.
• Parse each message's HTML with pyzmail and BeautifulSoup, walk the <a> tags, and keep the ones whose text mentions unsubscribing.
• Group those links by domain and dump them to a data.json file.

From there you get two paths. You can let it open every unsubscribe link automatically, or you can open a small view.html page, tick only the senders you actually want gone, and run a second script (unsubs.py) that opens just those. Each link is opened in the browser with Python's webbrowser module, optionally one at a time so you can confirm as you go.

What I learned

• IMAP is friendlier than it looks. Gmail's search plus a library like IMAPClient gets you most of the way without wrestling raw protocol commands.
• Real-world HTML is messy. Emails are not clean documents, so scraping links defensively — checking the link text and the URL scheme — mattered more than I expected.
• A human in the loop is a feature. Adding the "select which ones" step via a little HTML page made the tool feel safe to run, rather than something that fires off clicks blindly.

It's a tiny script, and it does exactly one thing, but it scratched a real itch and taught me the basics of programmatically reading a mailbox.

If you want to look at the code, here it is: UnsubscribeMail on GitHub.