Automate Unsubscribing from Newsletters via Gmail Filter

Hey there, Darian Vance here. Let’s talk about technical debt, but not in our codebase—in our inbox. For years, I had a graveyard of newsletters I’d signed up for. Every Monday morning meant another 30 minutes of manually clicking “Unsubscribe,” which felt like a colossal waste of focus. I finally decided to treat it like any other engineering problem: I automated it. This simple workflow I’m about to show you saves me a couple of hours a month and, more importantly, protects my deep work time. If your inbox is a source of constant distraction, this one’s for you.

Prerequisites

Before we dive in, make sure you have the following ready. We’re not reinventing the wheel, just connecting a few APIs.

• A Google Account (obviously, for Gmail).
• A Google Cloud Platform (GCP) Project. We need this to enable the Gmail API. It’s free for this level of usage.
• Python 3 installed on your system.
• Basic familiarity with creating a project directory and managing dependencies. I’ll skip the standard virtual environment setup since you likely have your own workflow for that. Just make sure to install the required libraries: google-api-python-client, google-auth-httplib2, google-auth-oauthlib, and requests.

The Step-by-Step Guide

Step 1: Create the Gmail “Trigger” Filter

The entire automation hinges on a simple Gmail filter. This is our trigger mechanism. We’ll create a filter that identifies emails with unsubscribe links and applies a unique label to them. The script will then look for that label.

1. In Gmail, go to Settings > See all settings > Filters and Blocked Addresses.
2. Click “Create a new filter”.
3. In the “Has the words” field, enter: "unsubscribe". This is broad, but it’s a reliable starting point.
4. Click “Create filter”.
5. Check the box for “Apply the label:” and create a new label. I call mine AutoUnsubscribe.
6. Optionally, you can check “Skip the Inbox (Archive it)” if you want to be aggressive, but for now, let’s just apply the label.
7. Click “Create filter”. Now, any incoming email with the word “unsubscribe” will get our target label.

Step 2: Configure the Google Cloud Project API Access

Now, we need to give our script permission to read and modify your emails. This is done via the Gmail API.

1. Go to your Google Cloud Console and select your project.
2. Navigate to APIs & Services > Library. Search for “Gmail API” and enable it.
3. Next, go to APIs & Services > OAuth consent screen.
   • Choose “External” for the User Type and click Create.
   • Fill out the required app information (app name, user support email). You can skip the rest for now.
   • On the Scopes page, click “Add or Remove Scopes”. Find and add the .../auth/gmail.modify scope. This is a powerful permission, as it allows reading and changing your emails, which is exactly what we need.
   • Add your own email address as a Test User.
4. Finally, go to APIs & Services > Credentials.
   • Click “Create Credentials” > “OAuth client ID”.
   • Select “Desktop app” as the Application type.
   • After creation, download the JSON file. Rename it to credentials.json and place it in your project directory. Treat this file like a password. Do not commit it to version control.

Step 3: The Python Unsubscribe Script

Alright, let’s get to the code. This script will authenticate, find emails with our AutoUnsubscribe label, parse them for an unsubscribe link, “click” it, and then clean up by removing the label and archiving the email.

I’ll lay out the full script first, then break down the logic.

import os.path
import base64
import re
import requests
from google.auth.transport.requests import Request
from google.oauth2.credentials import Credentials
from google_auth_oauthlib.flow import InstalledAppFlow
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError

# Define the scopes. If you modify these, delete token.json.
SCOPES = ['https://www.googleapis.com/auth/gmail.modify']
UNSUBSCRIBE_LABEL = 'AutoUnsubscribe' # Make sure this matches your Gmail label

def get_gmail_service():
    """Authenticates with Google and returns a Gmail service object."""
    creds = None
    if os.path.exists('token.json'):
        creds = Credentials.from_authorized_user_file('token.json', SCOPES)
    
    if not creds or not creds.valid:
        if creds and creds.expired and creds.refresh_token:
            creds.refresh(Request())
        else:
            flow = InstalledAppFlow.from_client_secrets_file('credentials.json', SCOPES)
            creds = flow.run_local_server(port=0)
        with open('token.json', 'w') as token:
            token.write(creds.to_json())
            
    return build('gmail', 'v1', credentials=creds)

def find_unsubscribe_link(html_body):
    """Parses HTML to find the 'List-Unsubscribe' header or a link."""
    # Regex for finding http/https links in the body
    url_pattern = re.compile(r'https?://[^\s"<>]+')
    links = url_pattern.findall(html_body)
    
    for link in links:
        if 'unsubscribe' in link.lower():
            return link
    return None

def process_messages(service):
    """Finds and processes emails with the unsubscribe label."""
    try:
        # Find the ID of our custom label
        results = service.users().labels().list(userId='me').execute()
        labels = results.get('labels', [])
        label_id = next((label['id'] for label in labels if label['name'] == UNSUBSCRIBE_LABEL), None)

        if not label_id:
            print(f"Error: Label '{UNSUBSCRIBE_LABEL}' not found.")
            return

        # Get messages with the specified label
        response = service.users().messages().list(userId='me', labelIds=[label_id]).execute()
        messages = response.get('messages', [])

        if not messages:
            print("No emails to process. All clean!")
            return

        print(f"Found {len(messages)} emails to process.")
        for message_item in messages:
            msg_id = message_item['id']
            msg = service.users().messages().get(userId='me', id=msg_id, format='full').execute()
            
            payload = msg['payload']
            body_data = ""

            if 'parts' in payload:
                for part in payload['parts']:
                    if part['mimeType'] == 'text/html':
                        body_data = part['body']['data']
                        break
            else:
                body_data = payload['body']['data']

            if not body_data:
                print(f"Could not find HTML body for message {msg_id}. Skipping.")
                continue

            html_body = base64.urlsafe_b64decode(body_data).decode('utf-8')
            unsubscribe_link = find_unsubscribe_link(html_body)

            if unsubscribe_link:
                try:
                    print(f"Found unsubscribe link: {unsubscribe_link}")
                    # Make a GET request to the unsubscribe link
                    requests.get(unsubscribe_link, timeout=10)
                    print(f"Successfully processed unsubscribe for message {msg_id}.")
                    
                    # Clean up: remove the label and archive the email
                    service.users().messages().modify(
                        userId='me',
                        id=msg_id,
                        body={'removeLabelIds': [label_id], 'addLabelIds': ['INBOX']} # You can change 'INBOX' to what fits your workflow
                    ).execute()
                    print(f"Cleaned up message {msg_id}.")
                except requests.RequestException as e:
                    print(f"Failed to access unsubscribe link for message {msg_id}: {e}")
            else:
                print(f"No unsubscribe link found for message {msg_id}. Manual review needed.")

    except HttpError as error:
        print(f'An error occurred: {error}')

if __name__ == '__main__':
    gmail_service = get_gmail_service()
    process_messages(gmail_service)

Code Breakdown:

• get_gmail_service(): This is standard boilerplate for authenticating with Google’s APIs. The first time you run it, it will open a browser window for you to authorize access. It then saves your credentials in a token.json file so you don’t have to log in every time.
• find_unsubscribe_link(): This is our core parsing logic. It uses a regular expression to find all URLs in the email’s HTML body and then returns the first one that contains the word “unsubscribe”. It’s not perfect, as some links are hidden behind text like “click here,” but in my experience, this catches about 90% of them.
• process_messages(): This function is the orchestrator. It gets the ID for our AutoUnsubscribe label, fetches all messages with that label, loops through them, extracts the HTML body, passes it to our link finder, and if a link is found, it uses the requests library to send a GET request to it—effectively “clicking” the link. Finally, it uses the messages.modify API call to remove our label so it doesn’t process the same email twice.

Pro Tip: The regex in find_unsubscribe_link is intentionally simple. You could improve it significantly by also looking for text like “manage your preferences” or by parsing the List-Unsubscribe header, which is a more robust method but adds complexity. I’ve found this simple approach is a great starting point.

Step 4: Schedule the Script

The final step is to run this script on a schedule. A cron job is perfect for this.

You can set it up to run once a week or once a day. I run mine every Monday morning.

Here’s an example cron entry to run the script every Monday at 2 AM:

0 2 * * 1 python3 script.py

Just make sure you’ve defined the correct path to your script and the python interpreter if they aren’t in your system’s PATH. On Windows, you can use the Task Scheduler to achieve the same result.

Common Pitfalls (Where I Usually Mess Up)

• Incorrect Scopes: The first time I set this up, I used a read-only scope (gmail.readonly). The script could find the emails but couldn’t remove the label, so it processed the same emails over and over. Make sure you use gmail.modify. If you change the scopes, you must delete token.json and re-authenticate.
• Rate Limiting: If you have thousands of emails to process on the first run, you might hit Google’s API rate limits. The script doesn’t handle this gracefully. My advice is to manually clean up your inbox first and let the script handle new emails going forward.
• Regex Failures: Some marketing emails use bizarrely formatted URLs or redirectors that the simple regex won’t catch. The script will print a message that it couldn’t find a link. You’ll still have to handle these few manually, but it’s better than doing all of them.

Conclusion

And that’s it. You’ve now offloaded a recurring, low-value task to a simple script. This is a classic DevOps mindset: identify a repetitive manual process and automate it. While it might seem small, reclaiming that time and mental energy compounds. You’ve built a small, personal automation engine that works for you 24/7. Now, go enjoy that cleaner inbox and the extra focus that comes with it.

Darian Vance

Lead Cloud Architect & DevOps Strategist

With over 12 years in system architecture and automation, Darian specializes in simplifying complex cloud infrastructures. An advocate for open-source solutions, he founded TechResolve to provide engineers with actionable, battle-tested troubleshooting guides and robust software alternatives.

🤖 Frequently Asked Questions