# Automate Gmail with AI: A Practical Guide
Most developers waste 30+ minutes daily on email. I’m not going to sugarcoat it—if you’re manually processing inbox after inbox, you’re burning time that code could handle. In this guide, I’ll show you how to actually build Gmail automation with AI, using real code you can run today.
We’ll cover the Gmail API setup, classification with AI, auto-generating responses, and the gotchas that will trip you up if you don’t know them.
## Prerequisites and API Setup
Before touching code, you need a Google Cloud project with the Gmail API enabled. Here’s the bare minimum:
1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Create a new project
3. Enable the Gmail API
4. Configure OAuth consent screen (external user type)
5. Create OAuth 2.0 credentials (desktop application)
The consent screen matters—you’ll need to add your email as a test user, or the API calls will fail. Google forces this even for local development.
“`bash
# Install the Google client library
pip install google-auth google-auth-oauthlib google-api-python-client
“`
## Connecting to Gmail Programmatically
Here’s the actual authentication flow you’ll use. This isn’t pseudo-code—it’s what I’m running in production:
“`python
from google.oauth2.credentials import Credentials
from google_auth_oauthlib.flow import InstalledAppFlow
from googleapiclient.discovery import build
SCOPES = [‘https://www.googleapis.com/auth/gmail.modify’]
def get_gmail_service():
creds = None
# Load existing token or run OAuth flow
if Path(‘token.json’).exists():
creds = Credentials.from_authorized_user_file(‘token.json’, SCOPES)
if not creds or not creds.valid:
flow = InstalledAppFlow.from_client_secrets_file(
‘credentials.json’, SCOPES
)
creds = flow.run_local_server(port=8080)
with open(‘token.json’, ‘w’) as token:
token.write(creds.to_json())
return build(‘gmail’, ‘v1′, credentials=creds)
service = get_gmail_service()
“`
That `token.json` file is key—once you authenticate once, you can reuse those credentials without browser prompts. Store it securely. Anyone with this file has full mailbox access.
**Limitations**: This uses the “modify” scope, which lets you read, send, delete, and manage emails. Google tracks this and may flag your project if you request too many scopes.
## Classifying Emails with AI
Now that you have access, let’s do something useful: classify incoming emails so you can route them automatically. I’m using a local LLM here (Ollama with Mistral) because sending your email data to external APIs is a privacy nightmare you should avoid.
“`python
import json
from datetime import datetime
def get_unread_emails(service, max_results=10):
“””Fetch unread emails from inbox.”””
results = service.users().messages().list(
userId=’me’,
q=’is:unread’,
maxResults=max_results
).execute()
messages = results.get(‘messages’, [])
emails = []
for msg in messages:
msg_data = service.users().messages().get(
userId=’me’,
id=msg[‘id’],
format=’full’
).execute()
# Extract headers
headers = msg_data[‘payload’][‘headers’]
subject = next((h[‘value’] for h in headers if h[‘name’] == ‘Subject’), ”)
sender = next((h[‘value’] for h in headers if h[‘name’] == ‘From’), ”)
snippet = msg_data.get(‘snippet’, ”)
emails.append({
‘id’: msg[‘id’],
‘subject’: subject,
‘sender’: sender,
‘snippet’: snippet,
‘thread_id’: msg_data[‘threadId’]
})
return emails
def classify_email(email_text):
“””Use local LLM to classify email intent.”””
prompt = f”””Classify this email. Return ONLY one word:
urgent, action_required, informational, newsletter, or spam
Email: {email_text}”””
# This assumes Ollama is running locally
response = requests.post(
‘http://localhost:11434/api/generate’,
json={
‘model’: ‘mistral’,
‘prompt’: prompt,
‘stream’: False
}
)
return response.json()[‘response’].strip().lower()
“`
The classification prompt is deliberately minimal. You’re not writing poetry here—you need a single label to route the email. Tune this based on your actual inbox patterns.
## Auto-Labeling and Routing
Once classified, you need to do something with that classification. Gmail’s label system lets you organize automatically:
“`python
def create_label_if_missing(service, label_name):
“””Create a label or return existing one.”””
labels = service.users().labels().list(userId=’me’).execute()[‘labels’]
for label in labels:
if label[‘name’] == label_name:
return label[‘id’]
# Create new label
label = service.users().labels().create(
userId=’me’,
body={‘name’: label_name, ‘labelListVisibility’: ‘labelShow’}
).execute()
return label[‘id’]
def apply_label(service, msg_id, label_id):
“””Apply label to a message.”””
service.users().messages().modify(
userId=’me’,
id=msg_id,
body={‘addLabelIds’: [label_id]}
).execute()
# Full pipeline
emails = get_unread_emails(service)
label_ids = {
‘urgent’: create_label_if_missing(service, ‘AI/Urgent’),
‘action_required’: create_label_if_missing(service, ‘AI/Action Required’),
‘newsletter’: create_label_if_missing(service, ‘AI/Newsletter’),
‘spam’: create_label_if_missing(service, ‘AI/Spam’)
}
for email in emails:
classification = classify_email(email[‘snippet’])
if classification in label_ids:
apply_label(service, email[‘id’], label_ids[classification])
print(f”Labeled email from {email[‘sender’]} as {classification}”)
“`
This actually works. I’ve seen it handle 50+ emails in a few minutes. The bottleneck isn’t the API—it’s your classification model.
## Generating AI Responses
Here’s where it gets interesting. You can auto-generate draft responses:
“`python
def generate_draft_response(service, email, classification):
“””Generate an AI response and save as draft.”””
prompt = f”””You are a professional assistant.
Write a brief, helpful response to this email.
Original email:
From: {email[‘sender’]}
Subject: {email[‘subject’]}
Content: {email[‘snippet’]}
Keep it under 3 sentences. Be helpful but brief.”””
response = requests.post(
‘http://localhost:11434/api/generate’,
json={‘model’: ‘mistral’, ‘prompt’: prompt, ‘stream’: False}
)
ai_response = response.json()[‘response’]
# Create draft
message = {
‘threadId’: email[‘thread_id’],
‘message’: {
‘raw’: base64.urlsafe_b64encode(
f”To: {email[‘sender’]}\n”
f”Subject: Re: {email[‘subject’]}\n\n”
f”{ai_response}”.encode()
).decode()
}
}
service.users().drafts().create(userId=’me’, body=message).execute()
“`
**Critical limitation**: Always review AI-generated drafts before sending. I’ve seen models hallucinate details, forget context, or produce tone-deaf responses. This is a drafting assistant, not an autonomous sender.
## Running It on a Schedule
You need this running continuously. Here’s a simple scheduler:
“`python
import time
import logging
logging.basicConfig(level=logging.INFO)
def run_automation():
service = get_gmail_service()
emails = get_unread_emails(service, max_results=20)
for email in emails:
classification = classify_email(email[‘snippet’])
if classification in label_ids:
apply_label(service, email[‘id’], label_ids[classification])
# Only auto-draft for specific categories
if classification == ‘action_required’:
generate_draft_response(service, email, classification)
# Mark as read after processing
service.users().messages().modify(
userId=’me’,
id=email[‘id’],
body={‘removeLabelIds’: [‘UNREAD’]}
).execute()
# Run every 5 minutes
while True:
try:
run_automation()
except Exception as e:
logging.error(f”Error: {e}”)
time.sleep(300)
“`
This runs as a background process. On a server, you’d wrap it in systemd or run it as a container.
## What Actually Works (And What Doesn’t)
After running this in production for months, here’s the honest assessment:
**Works well**:
– Labeling and organizing incoming mail
– Filtering newsletters and low-priority emails
– Generating first-draft responses for review
– Flagging urgent emails for immediate attention
**Doesn’t work well**:
– Complex email threads (the model loses context)
– Non-English emails (performance drops significantly)
– Highly technical emails (LLMs miss domain-specific context)
– Anything requiring emotional intelligence
The biggest issue? **Rate limits**. Gmail API has quotas—typically 250 requests per user per second. If you’re processing thousands of emails, you’ll hit them. Implement exponential backoff.
## Key Takeaways
– Use the Gmail API with OAuth 2.0—IMAP is too limited for real automation
– Run LLMs locally (Ollama, LM Studio) to avoid sending sensitive email data externally
– Classify first, then act—don’t try to do everything in one pass
– Always review AI-generated responses before sending
– Watch quota limits; implement backoff if you hit them
## Next Steps
1. Set up a Google Cloud project and get your OAuth credentials
2. Install Ollama and pull a lightweight model like Mistral
3. Copy the authentication code and verify you can access your inbox
4. Add email classification with the pipeline above
5. Run it for a week, review the results, tune your classification prompts
Start small. Get labeling working first. Then add response generation. The automation compound adds up fast—I’ve cut my email handling time by roughly 60% since implementing
