Gmail Enhanced

Advanced Gmail integration with powerful automation features.

Features

1. Advanced Search

• Complex query building (AND, OR, NOT)
• Date range filters
• Attachment filters
• Label filters
• Search within attachments

2. Label Management

• Create, rename, delete labels
• Nested labels (folders)
• Color customization
• Label statistics

3. Attachment Handling

• Download attachments
• Upload and send attachments
• Filter attachments by type/size
• Extract attachments to cloud storage

4. Email Processing

• Auto-categorize emails
• Extract data from emails
• Auto-reply rules
• Email templates
• Bounce detection

5. Email Parsing

• Extract structured data
• Parse invoices, receipts
• Extract contact info
• HTML parsing

Prerequisites

1. Enable Gmail API in Google Cloud Console
2. Create OAuth 2.0 credentials
3. Download credentials.json
4. Generate tokens.json (run once with authentication)

Configuration

export GMAIL_CREDENTIALS_PATH="/path/to/credentials.json"
export GMAIL_TOKEN_PATH="/path/to/tokens.json"

Or place credentials in default locations:

• ~/.credentials/gmail-credentials.json
• ~/.credentials/gmail-token.json

Usage

Send Email

from gmail_enhanced import GmailClient

gmail = GmailClient()

# Simple email
gmail.send(
    to="[email protected]",
    subject="Hello",
    body="Email content"
)

# With attachment
gmail.send(
    to="[email protected]",
    subject="Report",
    body="Please find the report attached",
    attachments=["report.pdf"]
)

Advanced Search

# Complex queries
results = gmail.search(
    query="from:[email protected]",
    label="INBOX",
    after="2024/01/01",
    has_attachments=True
)

# Search with OR
results = gmail.search_or([
    "subject:urgent",
    "label:important"
])

Label Management

# Create label
label = gmail.create_label("Projects/Work/Q1", color="#4A90E2")

# Get label stats
stats = gmail.get_label_stats("INBOX")

# Apply labels
gmail.add_labels(["Label1", "Label2"], message_ids)

Attachment Handling

# Download attachments from search results
attachments = gmail.search_attachments(
    query="subject:invoice",
    save_dir="./downloads"
)

# Upload attachment
gmail.send(
    to="[email protected]",
    subject="File",
    attachments=["/path/to/file.pdf"]
)

Auto-categorization

# Create rule
gmail.add_rule(
    name="Categorize invoices",
    query="subject:invoice has:attachment",
    add_labels=["Processed/Invoices"]
)

# Run rules
gmail.process_rules()

API Reference

Core Methods

Label Methods

Attachment Methods

Automation Methods

Parsing Methods

Email Query Syntax

Basic:
  from:[email protected]
  to:[email protected]
  subject:keyword
  "exact phrase"

Filters:
  after:2024/01/01
  before:2024/12/31
  older_than:7d
  newer_than:2h

Flags:
  has:attachment
  has:drive
  is:unread
  is:starred
  is:important

Labels:
  label:INBOX
  label:Work

Combinations:
  from:boss AND subject:urgent
  (from:alice OR from:bob) AND is:unread

Error Handling

Common errors:

• invalid_credentials: Re-authenticate
• rate_limit: Wait and retry
• not_found: Message ID invalid
• permission_denied: Check scopes

Scopes Required

https://www.googleapis.com/auth/gmail.readonly
https://www.googleapis.com/auth/gmail.send
https://www.googleapis.com/auth/gmail.labels
https://www.googleapis.com/auth/gmail.modify

Links

• Gmail API Documentation
• Google Cloud Console
• OAuth Setup Guide