Tired of Repetitive Emails? Automate Your Gmail Responses with Python!

Are you a student, freelancer, or perhaps someone who manages a small business inbox, constantly finding yourself typing the same replies to similar emails? Imagine if your computer could handle those repetitive tasks for you, freeing up your time for more important things. Sounds like magic, right? Well, it’s not magic, it’s automation with Python!

In this beginner-friendly guide, we’re going to dive into how you can use Python to connect with your Gmail account and automatically send replies to specific emails. Don’t worry if you’re new to programming; we’ll break down every step, explain technical terms, and provide clear code examples. By the end of this post, you’ll have a script that can act as your personal email assistant!

Why Automate Email Responses?

Before we jump into the “how,” let’s quickly touch upon the “why.” Automating email responses can be incredibly useful for:

Saving Time: No more manually drafting the same email over and over.
Improving Efficiency: Ensure quick, consistent replies, especially for common queries like “What are your business hours?” or “Where can I find your product catalog?”
Reducing Human Error: Automated responses are less prone to typos or missing information.
24/7 Availability: Your script can respond even when you’re away from your desk.

What You’ll Need Before We Start

To embark on this automation journey, you’ll need a few things:

Python Installed: Make sure you have Python 3.6 or newer installed on your computer. If not, you can download it from the official Python website.
A Google Account: This is essential for accessing Gmail and its API.
Basic Understanding of Python (Optional but helpful): We’ll keep the code simple, but familiarity with basic concepts like variables and functions will make it even easier to follow.

What is an API?

Before we go further, let’s understand a crucial term: API.
API stands for Application Programming Interface. Think of it as a waiter in a restaurant. You (your Python script) tell the waiter (the API) what you want (e.g., “send an email,” “read my unread emails”). The waiter then goes to the kitchen (Gmail’s servers), gets the job done, and brings the result back to you. You don’t need to know how the kitchen works internally; you just need to know how to talk to the waiter. The Gmail API allows your Python script to “talk” to Gmail and perform actions like reading, sending, and modifying emails.

Setting Up Your Google Cloud Project and Gmail API Access

This is the most “technical” part of the setup, but don’t worry, we’ll guide you through it. We need to tell Google that your Python script is allowed to access your Gmail account.

Go to the Google Cloud Console: Open your web browser and navigate to the Google Cloud Console. You’ll need to log in with your Google account.
Create a New Project:
- At the top of the page, click on the project dropdown (it usually shows “My First Project” or your current project name).
- Click “New Project.”
- Give your project a meaningful name (e.g., “Gmail Automation Script”) and click “Create.”
Enable the Gmail API:
- Once your project is created and selected, use the search bar at the top and type “Gmail API.”
- Click on “Gmail API” from the results.
- Click the “Enable” button.
Create OAuth 2.0 Client ID Credentials:
- In the left-hand menu, go to “APIs & Services” > “Credentials.”
- Click “Create Credentials” at the top and select “OAuth client ID.”
What is OAuth 2.0?

OAuth 2.0 is a secure way to give applications (like our Python script) limited access to your account information on other websites (like Google) without giving them your password. Instead, you grant specific permissions (e.g., “read emails” or “send emails”), and Google issues a “token” that the application can use. This token can be revoked at any time, adding an extra layer of security.
- For “Application type,” choose “Desktop app.”
- Give it a name (e.g., “Gmail Autoresponder Desktop”).
- Click “Create.”
Download Your credentials.json File:
- A pop-up will appear showing your Client ID and Client Secret.
- Click the “Download JSON” button.
- Rename the downloaded file to credentials.json (if it’s not already named that) and move it into the same folder where you will save your Python script. Keep this file secure! Do not share it publicly.

Installing Required Python Libraries

Now that Google knows your script exists, we need to install the Python libraries that will help your script communicate with the Gmail API.

Open your terminal or command prompt and run the following command:

pip install google-api-python-client google-auth-httplib2 google-auth-oauthlib

What is `pip`?

pip is the standard package manager for Python. Think of it as an app store for Python programs. It allows you to easily install and manage additional libraries (also called “packages” or “modules”) that extend Python’s capabilities. Here, we’re using pip to install libraries that Google provides to make interacting with their APIs much easier.

The Python Script – Step-by-Step

Let’s write our Python script! Create a new file named gmail_autoresponder.py (or anything you like) in the same folder as your credentials.json file.

1. Authentication and Building the Gmail Service

This part of the code handles the initial handshake with Google. It uses your credentials.json to get permission, and then it creates a token.json file after your first successful authorization. This token.json file stores your access tokens so you don’t have to re-authorize every time you run the script.

import os.path
import base64
from email.mime.text import MIMEText

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 authenticate_gmail():
    """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:
        service = build('gmail', 'v1', credentials=creds)
        print("Gmail API service built successfully.")
        return service
    except HttpError as error:
        print(f'An error occurred: {error}')
        return None

2. Fetching Unread Emails

Now, let’s create a function to find unread emails that meet certain criteria (e.g., from a specific sender or with a specific subject).

def search_unread_emails(service, query="is:unread"):
    """
    Searches for emails based on a query.
    Common queries:
    "is:unread" - all unread emails
    "from:sender@example.com is:unread" - unread emails from a specific sender
    "subject:\"Important Update\" is:unread" - unread emails with a specific subject
    """
    try:
        # Request a list of messages
        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)} unread messages matching the query.")
        return messages
    except HttpError as error:
        print(f'An error occurred while searching emails: {error}')
        return []

def get_email_details(service, msg_id):
    """Fetches details of a specific email message."""
    try:
        message = service.users().messages().get(userId='me', id=msg_id, format='full').execute()
        return message
    except HttpError as error:
        print(f'An error occurred while getting email details for ID {msg_id}: {error}')
        return None

3. Crafting and Sending Your Response

This function will create an email and send it. We’ll use the MIMEText library to properly format our email.

def create_message(sender, to, subject, message_text):
    """Create a message for an email."""
    message = MIMEText(message_text)
    message['to'] = to
    message['from'] = sender
    message['subject'] = subject
    # Encode the message into a base64 string, as required by Gmail API
    return {'raw': base64.urlsafe_b64encode(message.as_bytes()).decode()}

def send_message(service, user_id, message):
    """Send an email message."""
    try:
        # Send the message
        message = (service.users().messages().send(userId=user_id, body=message)
                   .execute())
        print(f'Message Id: {message["id"]} sent successfully to {message["payload"]["headers"][0]["value"]}')
        return message
    except HttpError as error:
        print(f'An error occurred while sending message: {error}')
        return None

4. Marking Emails as Read

After we’ve responded to an email, it’s good practice to mark it as read. This prevents your script from replying to the same email multiple times.

def mark_email_as_read(service, msg_id):
    """Marks an email as read."""
    try:
        # Modify the message: remove 'UNREAD' label
        service.users().messages().modify(userId='me', id=msg_id,
                                        body={'removeLabelIds': ['UNREAD']}).execute()
        print(f"Email ID {msg_id} marked as read.")
    except HttpError as error:
        print(f'An error occurred while marking email {msg_id} as read: {error}')

Putting It All Together: The Complete Autoresponder Script

Here’s the full script incorporating all the functions. Remember to customize the SENDER_EMAIL, AUTO_REPLY_SUBJECT, AUTO_REPLY_BODY, and the EMAIL_SEARCH_QUERY.

import os.path
import base64
from email.mime.text import MIMEText
import re # Regular Expression module for parsing email addresses

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'] # Allows reading, sending, and modifying emails.

SENDER_EMAIL = 'your_email@gmail.com' # <--- IMPORTANT: Change this to your actual email

AUTO_REPLY_SUBJECT = "Automatic Response: Thank You for Your Email!"

AUTO_REPLY_BODY = """
Dear [Sender Name Placeholder],

Thank you for reaching out! I have received your email and will get back to you as soon as possible.
Please note that this is an automated response.

Best regards,

[Your Name]
"""

EMAIL_SEARCH_QUERY = "is:unread subject:\"Inquiry\"" # <--- IMPORTANT: Customize your search query


def authenticate_gmail():
    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())

    try:
        service = build('gmail', 'v1', credentials=creds)
        print("Gmail API service built successfully.")
        return service
    except HttpError as error:
        print(f'An error occurred: {error}')
        return None

def search_unread_emails(service, query):
    try:
        response = service.users().messages().list(userId='me', q=query).execute()
        messages = []
        if 'messages' in response:
            messages.extend(response['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 the query: '{query}'")
        return messages
    except HttpError as error:
        print(f'An error occurred while searching emails: {error}')
        return []

def get_email_details(service, msg_id):
    try:
        message = service.users().messages().get(userId='me', id=msg_id, format='full').execute()
        return message
    except HttpError as error:
        print(f'An error occurred while getting email details for ID {msg_id}: {error}')
        return None

def create_message(sender, to, subject, message_text):
    message = MIMEText(message_text)
    message['to'] = to
    message['from'] = sender
    message['subject'] = subject
    return {'raw': base64.urlsafe_b64encode(message.as_bytes()).decode()}

def send_message(service, user_id, message):
    try:
        sent_message = (service.users().messages().send(userId=user_id, body=message).execute())
        recipient_header = next((header['value'] for header in sent_message['payload']['headers'] if header['name'] == 'To'), 'Unknown Recipient')
        print(f'Message Id: {sent_message["id"]} sent successfully to {recipient_header}')
        return sent_message
    except HttpError as error:
        print(f'An error occurred while sending message: {error}')
        return None

def mark_email_as_read(service, msg_id):
    try:
        service.users().messages().modify(userId='me', id=msg_id,
                                        body={'removeLabelIds': ['UNREAD']}).execute()
        print(f"Email ID {msg_id} marked as read.")
    except HttpError as error:
        print(f'An error occurred while marking email {msg_id} as read: {error}')


def main():
    service = authenticate_gmail()
    if not service:
        print("Failed to authenticate with Gmail API. Exiting.")
        return

    print(f"\nSearching for emails with query: '{EMAIL_SEARCH_QUERY}'")
    messages = search_unread_emails(service, EMAIL_SEARCH_QUERY)

    if not messages:
        print("No matching unread emails found. Nothing to do.")
        return

    processed_count = 0
    for msg in messages:
        msg_id = msg['id']
        email_details = get_email_details(service, msg_id)

        if not email_details:
            continue

        headers = email_details['payload']['headers']

        # Extract sender's email and name
        from_header = next((header['value'] for header in headers if header['name'] == 'From'), None)
        recipient_email = None
        sender_name = "there" # Default sender name

        if from_header:
            match = re.search(r'<(.*?)>', from_header) # Find email address inside angle brackets
            if match:
                recipient_email = match.group(1)
            else: # If no angle brackets, assume the whole header is the email
                recipient_email = from_header.strip()

            # Try to extract a name if available (e.g., "John Doe <john@example.com>")
            name_match = re.match(r'\"?([^\"<]+)\"?\s*<.*?>', from_header)
            if name_match:
                sender_name = name_match.group(1).strip()
            elif '@' in from_header: # If no explicit name, use part before @
                sender_name = from_header.split('@')[0].replace('.', ' ').title()


        if not recipient_email:
            print(f"Could not find recipient email for message ID: {msg_id}. Skipping.")
            continue

        # Prepare the personalized reply body
        personalized_reply_body = AUTO_REPLY_BODY.replace("[Sender Name Placeholder]", sender_name)

        print(f"\n--- Processing email from {from_header} (ID: {msg_id}) ---")
        print(f"Replying to: {recipient_email}")
        print(f"Reply Subject: {AUTO_REPLY_SUBJECT}")
        print(f"Reply Body:\n{personalized_reply_body}")

        # Create and send the reply
        reply_message = create_message(SENDER_EMAIL, recipient_email, AUTO_REPLY_SUBJECT, personalized_reply_body)
        send_message(service, 'me', reply_message)

        # Mark the original email as read
        mark_email_as_read(service, msg_id)
        processed_count += 1

    print(f"\nFinished processing. {processed_count} emails replied to and marked as read.")

if __name__ == '__main__':
    main()

Important Customizations:

SENDER_EMAIL: Replace 'your_email@gmail.com' with your actual Gmail address.
AUTO_REPLY_SUBJECT: Customize the subject line for your automated response.
AUTO_REPLY_BODY: Write the actual content of your automated email. You can use [Sender Name Placeholder] to automatically insert the sender’s name (if found).
EMAIL_SEARCH_QUERY: This is crucial! Customize this query to target the specific emails you want to auto-respond to.
- "is:unread": Responds to all unread emails. (Be careful with this!)
- "from:specific_sender@example.com is:unread": Responds only to unread emails from specific_sender@example.com.
- "subject:\"Meeting Request\" is:unread": Responds only to unread emails with “Meeting Request” in the subject.
- You can combine these, e.g., "from:support@yourcompany.com subject:\"Pricing Inquiry\" is:unread"

How to Run Your Script

Save the files: Make sure credentials.json and gmail_autoresponder.py are in the same folder.
Open your terminal/command prompt: Navigate to that folder using the cd command.
bash cd path/to/your/script/folder
Run the script:
bash python gmail_autoresponder.py
First Run Authorization:
- The first time you run the script, a web browser tab will automatically open.
- You’ll be prompted to log in to your Google account and grant your “Gmail Automation Script” project permission to “read, compose, and send, and permanently delete all your email from Gmail.”
- Carefully review the permissions. Since this is your own script, you should be fine, but always be cautious with granting access.
- After approval, a token.json file will be created in your script’s folder. This file securely stores your authorization tokens, so you won’t need to go through this browser step again unless token.json is deleted or the permissions SCOPES are changed.

Further Enhancements and Ideas

This script is a great starting point, but you can expand its capabilities significantly:

Scheduling: Use tools like cron (on Linux/macOS) or Task Scheduler (on Windows) to run your Python script automatically every hour or day, without manual intervention.
More Complex Logic:
- Read the email body and use keywords to send different types of replies.
- Integrate with a database or spreadsheet to fetch specific information for replies.
- Use natural language processing (NLP) to understand the intent of the email.
Error Handling: Add more robust error handling to gracefully deal with network issues or API limits.
Logging: Implement a logging system to keep a record of which emails were processed and what responses were sent.

Conclusion

Congratulations! You’ve successfully built a Python script to automate your Gmail responses. This is a powerful step into the world of automation, showing how a few lines of code can save you significant time and effort. Remember to always use such tools responsibly and be mindful of the permissions you grant.

Feel free to experiment with the EMAIL_SEARCH_QUERY and AUTO_REPLY_BODY to tailor the script to your specific needs. Happy automating!

Why Automate Email Responses?

What You’ll Need Before We Start

What is an API?

Setting Up Your Google Cloud Project and Gmail API Access

What is OAuth 2.0?

Installing Required Python Libraries

What is pip?

The Python Script – Step-by-Step

1. Authentication and Building the Gmail Service

2. Fetching Unread Emails

3. Crafting and Sending Your Response

4. Marking Emails as Read

Putting It All Together: The Complete Autoresponder Script

Important Customizations:

How to Run Your Script

Further Enhancements and Ideas

Conclusion

Comments