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#

bash

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#

python

from gmail_enhanced import GmailClient

gmail = GmailClient()

# Simple email
gmail.send(
    to="recipient@example.com",
    subject="Hello",
    body="Email content"
)

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

Advanced Search#

python

# Complex queries
results = gmail.search(
    query="from:boss@company.com",
    label="INBOX",
    after="2024/01/01",
    has_attachments=True
)

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

Label Management#

python

# 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#

python

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

# Upload attachment
gmail.send(
    to="recipient@example.com",
    subject="File",
    attachments=["/path/to/file.pdf"]
)

Auto-categorization#

python

# 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#

MethodDescriptionsend(to, subject, body, attachments, cc, bcc)Send emailsearch(query, max_results, label)Search emailsget_message(msg_id, format)Get email detailsdelete_message(msg_id)Move to trasharchive_message(msg_id)Archive email

Label Methods#

MethodDescriptioncreate_label(name, color)Create labelrename_label(old_name, new_name)Rename labeldelete_label(name)Delete labelget_labels()List all labelsget_label_stats(label)Get label statistics

Attachment Methods#

MethodDescriptiondownload_attachment(msg_id, attachment_id, save_path)Download attachmentsearch_attachments(query, save_dir)Search and downloadget_attachment_info(msg_id)List attachments

Automation Methods#

MethodDescriptionadd_rule(name, query, actions)Create processing ruleprocess_rules()Run all rulescreate_template(name, subject, body)Create email templatesend_template(template_name, to, variables)Send using template

Parsing Methods#

MethodDescriptionparse_email(msg_id)Extract structured dataextract_invoice(msg_id)Parse invoice dataextract_contacts(msg_id)Extract email addresses

Email Query Syntax#

text

Basic:
  from:user@example.com
  to:user@example.com
  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#

text

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