pontalk: Explore Python's Hidden Treasures!

Automating Gmail Labels and Filters with Python

Written by

ken

in

Do you ever feel overwhelmed by the sheer volume of emails flooding your Gmail inbox? Imagine a world where important messages are automatically sorted, newsletters are neatly tucked away, and promotional emails never clutter your main view. This isn’t a dream – it’s entirely possible with a little help from Python and the power of the Gmail API!

As an experienced technical writer, I’m here to guide you through the process of automating your Gmail organization. We’ll use simple language, step-by-step instructions, and clear explanations to make sure even beginners can follow along and reclaim their inbox sanity.

Why Automate Your Gmail?

Before we dive into the code, let’s understand why this is such a valuable skill:

  • Save Time: Manually sorting emails, applying labels, or deleting unwanted messages can eat up valuable minutes (or even hours!) each day. Automation handles this tedious work for you.
  • Stay Organized: A clean, well-labeled inbox means you can quickly find what you need. Important work emails, personal correspondence, and subscriptions can all have their designated spots.
  • Reduce Stress: Fewer unread emails and a less cluttered inbox can lead to a calmer, more productive day.
  • Customization: While Gmail offers built-in filters, Python gives you endless possibilities for highly specific and complex automation rules that might not be possible otherwise.

What Are We Going to Use?

To achieve our goal, we’ll be using a few key tools:

  • Python: This is a popular and beginner-friendly programming language. Think of it as the language we’ll use to tell Gmail what to do.
  • Gmail API: This is a set of rules and tools provided by Google that allows other programs (like our Python script) to interact with Gmail’s features. It’s like a secret handshake that lets our Python script talk to your Gmail account.
  • Google API Client Library for Python: This is a pre-written collection of Python code that makes it much easier to use the Gmail API. Instead of writing complex requests from scratch, we use functions provided by this library.

  • google-auth-oauthlib: This library helps us securely log in and get permission from you to access your Gmail data. It uses something called OAuth 2.0.

    • OAuth 2.0 (Open Authorization): Don’t let the name scare you! It’s a secure way for you to grant our Python script permission to access your Gmail without sharing your actual password. You’ll simply approve our script through your web browser.

Getting Started: Setting Up Your Google Cloud Project

This is the most crucial setup step. We need to tell Google that your Python script is a legitimate application that wants to access your Gmail.

1. Enable the Gmail API

  1. Go to the Google Cloud Console.
  2. If you don’t have a project, create a new one. Give it a descriptive name like “Gmail Automation Project.”
  3. Once your project is selected, use the search bar at the top and type “Gmail API.”
  4. Click on “Gmail API” from the results and then click the “Enable” button.

2. Create OAuth 2.0 Client ID Credentials

Your Python script needs specific “credentials” to identify itself to Google.

  1. In the Google Cloud Console, navigate to “APIs & Services” > “Credentials” (you can find this in the left-hand menu or search for it).
  2. Click “+ CREATE CREDENTIALS” at the top and choose “OAuth client ID.”
  3. For “Application type,” select “Desktop app.”
  4. Give it a name (e.g., “Gmail Automator Desktop App”).
  5. Click “CREATE.”
  6. A pop-up will appear showing your Client ID and Client secret. Crucially, click the “DOWNLOAD JSON” button.

  7. Rename the downloaded file to credentials.json and save it in the same folder where you’ll keep your Python script. This file contains the necessary “keys” for your script to authenticate.

    • credentials.json: This file holds sensitive information (your application’s ID and secret). Keep it safe and never share it publicly!

Understanding Gmail Labels and Filters

Before we automate them, let’s quickly review what Gmail’s built-in features are:

  • Labels: These are like customizable tags you can attach to emails. An email can have multiple labels. For example, an email could be labeled “Work,” “Project X,” and “Important.”
  • Filters: These are rules you set up in Gmail (e.g., “If an email is from newsletter@example.com AND contains the word ‘discount’, then apply the label ‘Promotions’ and mark it as read”). While powerful, creating many filters manually can be tedious, and Python allows for more dynamic, script-driven filtering.

Our Python script will essentially act as a super-smart filter, dynamically applying labels based on logic we define in our code.

Installing the Necessary Python Libraries

First things first, open your terminal or command prompt and install the libraries:

pip install google-api-python-client google-auth-oauthlib
  • pip: This is Python’s package installer. It helps you download and install additional tools (called “libraries” or “packages”) that aren’t part of Python by default.

Step-by-Step Python Implementation

Now, let’s write some Python code!

1. Authentication: Connecting to Your Gmail

This code snippet is crucial. It handles the process of securely logging you in and getting permission to access your Gmail. It will open a browser window for you to log in with your Google account.

import os.path

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

SCOPES = ["https://www.googleapis.com/auth/gmail.modify"]

def get_gmail_service():
    """Shows basic usage of the Gmail API.
    Lists the user's Gmail labels.
    """
    creds = None
    # The file token.json stores the user's access and refresh tokens, and is
    # created automatically when the authorization flow completes for the first
    # time.
    if os.path.exists("token.json"):
        creds = Credentials.from_authorized_user_file("token.json", SCOPES)
    # If there are no (valid) credentials available, let the user log in.
    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)
        # Save the credentials for the next run
        with open("token.json", "w") as token:
            token.write(creds.to_json())

    try:
        # Build the Gmail service object
        service = build("gmail", "v1", credentials=creds)
        print("Successfully connected to Gmail API!")
        return service
    except HttpError as error:
        print(f"An error occurred: {error}")
        return None

if __name__ == '__main__':
    service = get_gmail_service()
    if service:
        print("Service object created. Ready to interact with Gmail!")
  • SCOPES: This is very important. It tells Google what your application wants to do with your Gmail account. gmail.modify means we want to be able to read, send, delete, and change labels. If you only wanted to read emails, you’d use a different scope.
  • token.json: After you log in for the first time, your login information (tokens) will be saved in a file called token.json. This means you won’t have to log in every single time you run the script, as long as this file exists and is valid.

Run this script once. It will open a browser window, ask you to log in with your Google account, and grant permissions to your application. After successful authorization, token.json will be created in your script’s directory.

2. Finding or Creating a Gmail Label

We need a label to apply to our emails. Let’s create a function that checks if a label exists and, if not, creates it.

def get_or_create_label(service, label_name):
    """
    Checks if a label exists, otherwise creates it and returns its ID.
    """
    try:
        # List all existing labels
        results = service.users().labels().list(userId='me').execute()
        labels = results.get('labels', [])

        # Check if our label already exists
        for label in labels:
            if label['name'] == label_name:
                print(f"Label '{label_name}' already exists with ID: {label['id']}")
                return label['id']

        # If not found, create the new label
        body = {
            'name': label_name,
            'labelListVisibility': 'labelShow', # Makes the label visible in the label list
            'messageListVisibility': 'show' # Makes the label visible on messages in the list
        }
        created_label = service.users().labels().create(userId='me', body=body).execute()
        print(f"Label '{label_name}' created with ID: {created_label['id']}")
        return created_label['id']

    except HttpError as error:
        print(f"An error occurred while getting/creating label: {error}")
        return None

3. Searching for Messages and Applying Labels

Now for the core logic! We’ll search for emails that match certain criteria (e.g., from a specific sender) and then apply our new label.

def search_messages(service, query):
    """
    Search for messages matching a query (e.g., 'from:sender@example.com').
    Returns a list of message IDs.
    """
    try:
        response = service.users().messages().list(userId='me', q=query).execute()
        messages = []
        if 'messages' in response:
            messages.extend(response['messages'])

        # Handle pagination if there are many messages
        while 'nextPageToken' in response:
            page_token = response['nextPageToken']
            response = service.users().messages().list(
                userId='me', q=query, pageToken=page_token
            ).execute()
            if 'messages' in response:
                messages.extend(response['messages'])

        print(f"Found {len(messages)} messages matching query: '{query}'")
        return messages

    except HttpError as error:
        print(f"An error occurred while searching messages: {error}")
        return []

def apply_label_to_messages(service, message_ids, label_id):
    """
    Applies a given label to a list of message IDs.
    """
    if not message_ids:
        print("No messages to label.")
        return

    try:
        # Batch modify messages
        body = {
            'ids': [msg['id'] for msg in message_ids], # List of message IDs
            'addLabelIds': [label_id],                 # Label to add
            'removeLabelIds': []                       # No labels to remove in this case
        }
        service.users().messages().batchModify(userId='me', body=body).execute()
        print(f"Successfully applied label to {len(message_ids)} messages.")

    except HttpError as error:
        print(f"An error occurred while applying label: {error}")
  • q=query: This is how you specify your search criteria, similar to how you search in Gmail’s search bar. Examples:
    • from:sender@example.com
    • subject:"Monthly Newsletter"
    • has:attachment
    • is:unread
    • You can combine them: from:sender@example.com subject:"Updates" after:2023/01/01

4. Putting It All Together: A Complete Example Script

Let’s create a full script to automate labeling all emails from a specific sender with a new custom label.

import os.path

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

SCOPES = ["https://www.googleapis.com/auth/gmail.modify"]

def get_gmail_service():
    """
    Handles authentication and returns a Gmail API service object.
    """
    creds = None
    # Check if a token.json file exists (from a previous login)
    if os.path.exists("token.json"):
        creds = Credentials.from_authorized_user_file("token.json", SCOPES)

    # If no valid credentials, or they're expired, prompt user to log in
    if not creds or not creds.valid:
        if creds and creds.expired and creds.refresh_token:
            creds.refresh(Request())
        else:
            # If no creds or refresh token, start the full OAuth flow
            flow = InstalledAppFlow.from_client_secrets_file(
                "credentials.json", SCOPES
            )
            creds = flow.run_local_server(port=0)
        # Save the new/refreshed credentials for future runs
        with open("token.json", "w") as token:
            token.write(creds.to_json())

    try:
        # Build the Gmail service object using the authenticated credentials
        service = build("gmail", "v1", credentials=creds)
        print("Successfully connected to Gmail API!")
        return service
    except HttpError as error:
        print(f"An error occurred during API service setup: {error}")
        return None

def get_or_create_label(service, label_name):
    """
    Checks if a label exists by name, otherwise creates it and returns its ID.
    """
    try:
        # List all existing labels for the user
        results = service.users().labels().list(userId='me').execute()
        labels = results.get('labels', [])

        # Iterate through existing labels to find a match
        for label in labels:
            if label['name'] == label_name:
                print(f"Label '{label_name}' already exists with ID: {label['id']}")
                return label['id']

        # If the label wasn't found, create a new one
        body = {
            'name': label_name,
            'labelListVisibility': 'labelShow', # Make it visible in the label list
            'messageListVisibility': 'show'     # Make it visible on messages
        }
        created_label = service.users().labels().create(userId='me', body=body).execute()
        print(f"Label '{label_name}' created with ID: {created_label['id']}")
        return created_label['id']

    except HttpError as error:
        print(f"An error occurred while getting/creating label: {error}")
        return None

def search_messages(service, query):
    """
    Searches for messages in Gmail matching the given query string.
    Returns a list of message dictionaries (each with an 'id').
    """
    try:
        response = service.users().messages().list(userId='me', q=query).execute()
        messages = []
        if 'messages' in response:
            messages.extend(response['messages'])

        # Loop to get all messages if there are multiple pages of results
        while 'nextPageToken' in response:
            page_token = response['nextPageToken']
            response = service.users().messages().list(
                userId='me', q=query, pageToken=page_token
            ).execute()
            if 'messages' in response:
                messages.extend(response['messages'])

        print(f"Found {len(messages)} messages matching query: '{query}'")
        return messages

    except HttpError as error:
        print(f"An error occurred while searching messages: {error}")
        return []

def apply_label_to_messages(service, message_ids, label_id, mark_as_read=False):
    """
    Applies a given label to a list of message IDs. Optionally marks them as read.
    """
    if not message_ids:
        print("No messages to label. Skipping.")
        return

    try:
        # Prepare the body for batch modification
        body = {
            'ids': [msg['id'] for msg in message_ids], # List of message IDs to modify
            'addLabelIds': [label_id],                 # Label(s) to add
            'removeLabelIds': []                       # Label(s) to remove (e.g., 'UNREAD' if marking as read)
        }

        if mark_as_read:
            body['removeLabelIds'].append('UNREAD') # Add 'UNREAD' to remove list

        service.users().messages().batchModify(userId='me', body=body).execute()
        print(f"Successfully processed {len(message_ids)} messages: applied label '{label_id}'" + 
              (f" and marked as read." if mark_as_read else "."))

    except HttpError as error:
        print(f"An error occurred while applying label: {error}")

def main():
    """
    Main function to run the Gmail automation process.
    """
    # 1. Get the Gmail API service object
    service = get_gmail_service()
    if not service:
        print("Failed to get Gmail service. Exiting.")
        return

    # --- Configuration for your automation ---
    TARGET_SENDER = "newsletter@example.com" # Replace with the sender you want to filter
    TARGET_LABEL_NAME = "Newsletters"        # Replace with your desired label name
    MARK_AS_READ_AFTER_LABELING = True       # Set to True to mark processed emails as read

    # 2. Get or create the target label
    label_id = get_or_create_label(service, TARGET_LABEL_NAME)
    if not label_id:
        print(f"Failed to get or create label '{TARGET_LABEL_NAME}'. Exiting.")
        return

    # 3. Search for messages from the target sender that are currently unread
    # We add '-label:Newsletters' to ensure we don't re-process already labeled emails
    # And 'is:unread' to target only unread ones (optional, remove if you want to process all)
    search_query = f"from:{TARGET_SENDER} is:unread -label:{TARGET_LABEL_NAME}"
    messages_to_process = search_messages(service, search_query)

    # 4. Apply the label to the found messages (and optionally mark as read)
    if messages_to_process:
        apply_label_to_messages(service, messages_to_process, label_id, MARK_AS_READ_AFTER_LABELING)
    else:
        print(f"No new unread messages from '{TARGET_SENDER}' found to label.")

    print("\nGmail automation task completed!")

if __name__ == '__main__':
    main()

Remember to replace "newsletter@example.com" and "Newsletters" with the sender and label name relevant to your needs!

To run this script:
1. Save all the code in a file named gmail_automator.py (or any .py name).
2. Make sure credentials.json is in the same directory.
3. Open your terminal or command prompt, navigate to that directory, and run:
bash
python gmail_automator.py
4. The first time, it will open a browser for authentication. Subsequent runs will use token.json.

Conclusion

Congratulations! You’ve just taken a big step towards a more organized and stress-free inbox. By leveraging Python and the Gmail API, you can automate repetitive tasks, ensure important emails are always categorized correctly, and spend less time managing your inbox and more time on what matters.

This example is just the beginning. You can expand on this script to:
* Filter based on subject lines or keywords within the email body.
* Automatically archive messages after labeling.
* Delete promotional emails older than a certain date.
* Send automated replies.

The possibilities are endless, and your inbox will thank you for it! Happy automating!

Comments

Leave a Reply

More posts