astoreyai/google-gmail-integration

Gmail Integration

Comprehensive Gmail integration enabling email search, message management, sending, label organization, attachment handling, and workflow automation through the Gmail API v1.

Quick Start

When asked to work with Gmail:

1. Authenticate: Set up OAuth2 credentials (one-time setup)
2. Search emails: Find messages by sender, subject, date, or content
3. Read messages: Get email content and attachments
4. Send emails: Compose and send messages
5. Organize: Create labels, apply filters, archive messages
6. Automate: Process emails based on rules

Prerequisites

One-Time Setup

1. Enable Gmail API:

# Visit Google Cloud Console
# https://console.cloud.google.com/

# Enable Gmail API for your project
# APIs & Services > Enable APIs and Services > Gmail API

2. Create OAuth2 Credentials:

# In Google Cloud Console:
# APIs & Services > Credentials > Create Credentials > OAuth client ID
# Application type: Desktop app
# Download credentials as credentials.json

3. Install Dependencies:

pip install google-auth google-auth-oauthlib google-auth-httplib2 google-api-python-client --break-system-packages

4. Initial Authentication:

python scripts/authenticate.py
# Opens browser for Google sign-in
# Saves token.json for future use

See reference/setup-guide.md for detailed setup instructions.

Core Operations

Search Emails

Basic search:

# Search by keyword
python scripts/search_emails.py --query "project update"

# Search by sender
python scripts/search_emails.py --from "[email protected]"

# Search by subject
python scripts/search_emails.py --subject "Weekly Report"

# Search unread
python scripts/search_emails.py --unread

# Search with label
python scripts/search_emails.py --label "Important"

Advanced search queries:

# Combination search
query = "from:[email protected] subject:urgent is:unread"

# Date ranges
query = "after:2025/01/01 before:2025/01/31"

# Has attachment
query = "has:attachment filename:pdf"

# Size filters
query = "larger:10M"

# Categories
query = "category:primary"
query = "category:social"
query = "category:promotions"

# Boolean operators
query = "(from:[email protected] OR from:[email protected]) subject:meeting"

See reference/search-syntax.md for complete search reference.

Read Messages

Get message content:

# Read email
python scripts/read_email.py --message-id MESSAGE_ID

# Get specific format
python scripts/read_email.py --message-id MESSAGE_ID --format full
python scripts/read_email.py --message-id MESSAGE_ID --format minimal
python scripts/read_email.py --message-id MESSAGE_ID --format raw

Extract information:

# Get headers
python scripts/get_headers.py --message-id MESSAGE_ID

# Get body text
python scripts/get_body.py --message-id MESSAGE_ID --format text
python scripts/get_body.py --message-id MESSAGE_ID --format html

# List attachments
python scripts/list_attachments.py --message-id MESSAGE_ID

Download attachments:

# Download all attachments
python scripts/download_attachments.py --message-id MESSAGE_ID --output ./downloads/

# Download specific attachment
python scripts/download_attachments.py --message-id MESSAGE_ID --filename "report.pdf"

Send Emails

Simple send:

# Send plain text
python scripts/send_email.py \
  --to "[email protected]" \
  --subject "Hello" \
  --body "Email content here"

# Send to multiple recipients
python scripts/send_email.py \
  --to "[email protected],[email protected]" \
  --cc "[email protected]" \
  --subject "Team Update" \
  --body "Content here"

Send with attachments:

python scripts/send_email.py \
  --to "[email protected]" \
  --subject "Report" \
  --body "Please see attached" \
  --attachments "./report.pdf,./data.xlsx"

Send HTML email:

python scripts/send_email.py \
  --to "[email protected]" \
  --subject "Newsletter" \
  --html-body "./newsletter.html"

Reply to message:

python scripts/reply_email.py \
  --message-id MESSAGE_ID \
  --body "Thanks for your email..."

Forward message:

python scripts/forward_email.py \
  --message-id MESSAGE_ID \
  --to "[email protected]" \
  --body "FYI"

Label Management

Create labels:

# Create label
python scripts/create_label.py --name "Project Alpha"

# Create nested label
python scripts/create_label.py --name "Projects/Alpha"

# Create with settings
python scripts/create_label.py \
  --name "Important" \
  --label-list-visibility show \
  --message-list-visibility show

Apply labels:

# Add label to message
python scripts/add_label.py --message-id MESSAGE_ID --label "Important"

# Add multiple labels
python scripts/add_label.py --message-id MESSAGE_ID --labels "Work,Urgent"

# Remove label
python scripts/remove_label.py --message-id MESSAGE_ID --label "Inbox"

List labels:

# Get all labels
python scripts/list_labels.py

# Get label ID
python scripts/get_label_id.py --name "Project Alpha"

Message Management

Mark as read/unread:

# Mark as read
python scripts/mark_read.py --message-id MESSAGE_ID

# Mark as unread
python scripts/mark_unread.py --message-id MESSAGE_ID

Archive/Trash:

# Archive message (remove from Inbox)
python scripts/archive_email.py --message-id MESSAGE_ID

# Move to trash
python scripts/trash_email.py --message-id MESSAGE_ID

# Delete permanently
python scripts/delete_email.py --message-id MESSAGE_ID

Batch operations:

# Archive all read emails older than 30 days
python scripts/batch_archive.py --days 30 --read-only

# Delete all emails from sender
python scripts/batch_delete.py --from "[email protected]"

# Mark all as read
python scripts/batch_mark_read.py --label "Inbox"

Common Workflows

Workflow 1: Process Unread Emails

Scenario: Read unread emails and categorize

# Get unread emails
python scripts/process_unread.py \
  --label-rules rules.json \
  --mark-read

# rules.json example:
{
  "rules": [
    {
      "condition": "from:[email protected]",
      "action": "add_label",
      "label": "Important"
    },
    {
      "condition": "subject:invoice",
      "action": "add_label",
      "label": "Finance"
    }
  ]
}

Workflow 2: Email to Task Conversion

Scenario: Convert emails into task format

# Extract tasks from emails
python scripts/email_to_tasks.py \
  --query "label:To-Do" \
  --output tasks.json \
  --mark-done

Workflow 3: Automated Responses

Scenario: Send auto-replies based on conditions

# Auto-respond to specific emails
python scripts/auto_respond.py \
  --query "from:[email protected] subject:urgent" \
  --template response_template.txt \
  --label "Auto-Responded"

Workflow 4: Email Backup

Scenario: Download emails for backup

# Backup all emails
python scripts/backup_emails.py \
  --output ./email_backup/ \
  --format mbox

# Backup specific label
python scripts/backup_emails.py \
  --label "Important" \
  --output ./important_backup/ \
  --include-attachments

Workflow 5: Email Analytics

Scenario: Analyze email patterns

# Generate email statistics
python scripts/email_stats.py \
  --start-date 2025-01-01 \
  --end-date 2025-01-31 \
  --output stats.json

# Top senders
python scripts/top_senders.py --limit 10

# Email volume by day
python scripts/email_volume.py --days 30

Search Query Syntax

Operators

# Sender/Recipient
"from:[email protected]"
"to:[email protected]"
"cc:[email protected]"
"bcc:[email protected]"

# Subject
"subject:meeting"
"subject:(status report)"

# Date
"after:2025/01/01"
"before:2025/12/31"
"older_than:2d"  # days
"newer_than:7d"

# Status
"is:unread"
"is:read"
"is:starred"
"is:important"

# Has
"has:attachment"
"has:drive"
"has:document"
"has:spreadsheet"
"has:presentation"
"has:youtube"

# Size
"larger:10M"
"smaller:1M"
"size:5M"

# Category
"category:primary"
"category:social"
"category:promotions"
"category:updates"
"category:forums"

# Label
"label:important"
"label:work"
"-label:inbox"  # exclude inbox

# Filename
"filename:pdf"
"filename:report.xlsx"

# In
"in:inbox"
"in:trash"
"in:spam"
"in:anywhere"  # includes spam and trash

# Boolean
"OR"  # Must be uppercase
"AND"  # Implied, can be explicit
"-"   # NOT operator
"()"  # Grouping

Example Queries

# Unread emails from boss
"from:[email protected] is:unread"

# Large emails with attachments
"has:attachment larger:5M"

# Recent important unread
"is:important is:unread newer_than:7d"

# Specific sender, subject, with PDF
"from:[email protected] subject:invoice has:attachment filename:pdf"

# Multiple senders
"(from:[email protected] OR from:[email protected]) subject:meeting"

# Date range with keyword
"after:2025/01/01 before:2025/01/31 project update"

# Exclude categories
"-category:promotions -category:social is:unread"

Message Format Options

Format Types

# Minimal - IDs and labels only
format = 'minimal'

# Full - Complete message with body and headers
format = 'full'

# Raw - Raw MIME message (for forwarding)
format = 'raw'

# Metadata - Headers and labels without body
format = 'metadata'

Accessing Message Parts

# Get headers
headers = message['payload']['headers']
for header in headers:
    if header['name'] == 'Subject':
        subject = header['value']
    elif header['name'] == 'From':
        sender = header['value']

# Get body (plain text)
parts = message['payload'].get('parts', [])
for part in parts:
    if part['mimeType'] == 'text/plain':
        body = base64.urlsafe_b64decode(part['body']['data']).decode()

# Get attachments
for part in parts:
    if part.get('filename'):
        attachment_id = part['body']['attachmentId']

Sending Email Formats

Plain Text

from email.mime.text import MIMEText
import base64

message = MIMEText('Email body')
message['to'] = '[email protected]'
message['subject'] = 'Test Email'

raw = base64.urlsafe_b64encode(message.as_bytes()).decode()

HTML Email

from email.mime.multipart import MIMEMultipart
from email.mime.text import MIMEText

message = MIMEMultipart('alternative')
message['to'] = '[email protected]'
message['subject'] = 'HTML Email'

text = "Plain text version"
html = "<html><body><h1>HTML Version</h1></body></html>"

part1 = MIMEText(text, 'plain')
part2 = MIMEText(html, 'html')

message.attach(part1)
message.attach(part2)

With Attachments

from email.mime.base import MIMEBase
from email import encoders
import os

message = MIMEMultipart()
message['to'] = '[email protected]'
message['subject'] = 'With Attachment'

# Add body
body = MIMEText('Please see attached')
message.attach(body)

# Add attachment
with open('file.pdf', 'rb') as f:
    part = MIMEBase('application', 'octet-stream')
    part.set_payload(f.read())
    encoders.encode_base64(part)
    part.add_header(
        'Content-Disposition',
        f'attachment; filename={os.path.basename("file.pdf")}'
    )
    message.attach(part)

Label Visibility

Label list visibility:

• labelShow - Show in label list
• labelHide - Hide from label list

Message list visibility:

• show - Show label in message list
• hide - Hide label in message list

API Rate Limits

Gmail API quotas:

• Queries per day: 1,000,000,000
• Queries per 100 seconds per user: 250
• Send message: 100 per day per user (can request increase)

Best practices:

• Batch requests when possible
• Use partial responses to reduce data
• Implement exponential backoff
• Cache message IDs and metadata

OAuth Scopes

# Full access (read, send, delete)
'https://www.googleapis.com/auth/gmail.modify'

# Read-only
'https://www.googleapis.com/auth/gmail.readonly'

# Send only
'https://www.googleapis.com/auth/gmail.send'

# Labels only
'https://www.googleapis.com/auth/gmail.labels'

# Compose (draft and send)
'https://www.googleapis.com/auth/gmail.compose'

# Insert (add messages)
'https://www.googleapis.com/auth/gmail.insert'

# Metadata only
'https://www.googleapis.com/auth/gmail.metadata'

Choose the minimal scope needed for your use case.

Scripts Reference

Authentication:

• authenticate.py - Initial OAuth setup
• refresh_token.py - Refresh token

Search:

• search_emails.py - Search with queries
• find_by_sender.py - Quick sender search
• find_unread.py - Get unread messages

Read:

• read_email.py - Read message content
• get_headers.py - Extract headers
• get_body.py - Get message body
• list_attachments.py - List attachments
• download_attachments.py - Download files

Send:

• send_email.py - Send new email
• reply_email.py - Reply to message
• forward_email.py - Forward message
• send_bulk.py - Send to multiple recipients

Labels:

• create_label.py - Create new label
• list_labels.py - Get all labels
• add_label.py - Apply label to message
• remove_label.py - Remove label

Manage:

• mark_read.py - Mark as read
• mark_unread.py - Mark as unread
• archive_email.py - Archive message
• trash_email.py - Move to trash
• delete_email.py - Permanent delete

Batch:

• batch_archive.py - Archive multiple
• batch_delete.py - Delete multiple
• batch_mark_read.py - Mark multiple read

Automation:

• process_unread.py - Process unread emails
• auto_respond.py - Automated responses
• email_to_tasks.py - Extract tasks
• apply_filters.py - Apply rule-based filters

Analytics:

• email_stats.py - Usage statistics
• top_senders.py - Most frequent senders
• email_volume.py - Volume over time

Best Practices

1. Use specific queries: Narrow searches reduce processing time
2. Batch operations: Process multiple messages in single API call
3. Cache data: Store message IDs and metadata locally
4. Handle pagination: Use pageToken for large result sets
5. Respect quotas: Monitor API usage
6. Error handling: Implement retry logic with backoff
7. Secure tokens: Never commit token.json to version control
8. Minimal scopes: Request only needed permissions

Integration Examples

See examples/ for complete workflows:

• examples/email-automation.md - Automated email processing
• examples/task-integration.md - Email to task conversion
• examples/reporting.md - Email analytics and reporting
• examples/backup-strategy.md - Email backup approaches

Troubleshooting

"Token expired"

rm token.json
python scripts/authenticate.py

"Insufficient permissions"

• Check SCOPES in authenticate.py
• Delete token.json and re-auth with new scopes

"Message not found"

• Message may have been deleted
• Check if in trash or spam

"Rate limit exceeded"

• Implement delays between requests
• Use batch operations
• Request quota increase if needed

Reference Documentation

• reference/setup-guide.md - Setup instructions
• reference/search-syntax.md - Complete search reference
• reference/api-reference.md - API documentation
• reference/email-formats.md - MIME and format reference