Gmail Client for Opportunity Tracker

A modular Gmail client that provides flexible email access through both Gmail API (default) and mbox file import (fallback). Designed for integration into broader applications requiring email processing capabilities.

Overview

The Gmail client defaults to using the Gmail API for live email access but can seamlessly fall back to processing mbox files when API access is unavailable, credentials are missing, or when working with archived email data.

Features

Primary Method: Gmail API (Default)

• Live email access from Gmail accounts
• OAuth2 authentication with token persistence
• Advanced search capabilities using Gmail query syntax
• Real-time data with full Gmail metadata
• Rate limiting compliance built-in

Fallback Method: Mbox Import

• No authentication required - works entirely offline
• Archive processing for historical email analysis
• Portable email data from various email clients
• Same data structure as API responses for consistent integration

Quick Start

1. Installation

pip install -r requirements.txt

2. Basic Usage

Default: Gmail API

from gmail_client import GmailClient

# Initialize and authenticate
client = GmailClient()
if client.authenticate():
    # Fetch recent emails
    emails = client.get_recent_emails(days=7, max_results=20)
    
    # Search emails
    business_emails = client.search_emails("subject:meeting OR subject:proposal")

Fallback: Mbox Files

from gmail_client import GmailClient

# No authentication needed for mbox
client = GmailClient()

# Load from mbox file
emails = client.load_from_mbox('/path/to/mailbox.mbox', max_messages=50)

# Search within mbox
meeting_emails = client.search_mbox_emails('/path/to/mailbox.mbox', 'meeting')

Setup Instructions

Gmail API Setup (Primary Method)

1. Create Google Cloud Project

   • Go to Google Cloud Console
   • Create a new project or select existing one

2. Enable Gmail API

   • Navigate to "APIs & Services" > "Library"
   • Search for "Gmail API" and enable it

3. Create Credentials

   • Go to "APIs & Services" > "Credentials"
   • Click "Create Credentials" > "OAuth client ID"
   • Choose "Desktop application"
   • Download the JSON file as credentials.json

4. Place Credentials

   # Place in your project root or specify path
   mv ~/Downloads/credentials.json ./credentials.json

Mbox Setup (Fallback Method)

No setup required! Simply provide the path to your mbox file:

# Export from email clients like:
# - Thunderbird: Tools > Export
# - Apple Mail: Mailbox > Export Mailbox
# - Outlook: File > Open & Export > Import/Export
emails = client.load_from_mbox('/path/to/exported.mbox')

Usage Patterns

Robust Application Integration

def get_emails_with_fallback(mbox_path=None):
    """Get emails with API-first, mbox-fallback strategy."""
    client = GmailClient()
    
    # Try API first (default)
    if client.authenticate():
        print("Using Gmail API...")
        return client.get_recent_emails(days=30)
    
    # Fallback to mbox if API fails
    elif mbox_path and os.path.exists(mbox_path):
        print(f"Falling back to mbox: {mbox_path}")
        return client.load_from_mbox(mbox_path)
    
    else:
        print("No email source available")
        return []

# Usage
emails = get_emails_with_fallback('/backup/emails.mbox')

Unified Data Processing

Both methods return the same data structure:

{
    'id': 'message_id',
    'thread_id': 'thread_id',  # None for mbox
    'subject': 'Email Subject',
    'sender': 'sender@example.com',
    'date': datetime_object,
    'date_str': 'original_date_string',
    'message_id': 'Message-ID_header',
    'body': 'email_body_text',
    'snippet': 'preview_text...',
    'labels': ['INBOX', 'IMPORTANT'],  # Empty for mbox
    'source': 'api' or 'mbox'  # Source tracking
}

API Methods

Gmail API Methods (Default)

• authenticate() - OAuth2 authentication
• get_recent_emails(days=7, max_results=50, query_filter="") - Fetch recent emails
• search_emails(query, max_results=50) - Search with Gmail syntax
• get_email_by_id(message_id) - Fetch specific email

Mbox Methods (Fallback)

• load_from_mbox(mbox_path, max_messages=None) - Load emails from mbox
• search_mbox_emails(mbox_path, search_term, search_in='all', max_results=None) - Search mbox

Example Scripts

Interactive Demo

cd scripts/
python3 example_fetch_emails.py
# Choose: (1) Gmail API, (2) Mbox import, (3) Both

Direct Testing

python3 test_mbox_demo.py  # Tests mbox functionality directly

Error Handling

The client includes comprehensive error handling:

# API errors
try:
    emails = client.get_recent_emails()
except RuntimeError as e:
    print(f"Authentication required: {e}")

# Mbox errors  
try:
    emails = client.load_from_mbox('nonexistent.mbox')
except FileNotFoundError as e:
    print(f"Mbox file not found: {e}")

When to Use Each Method

Use Gmail API (Default) When:

• ✅ Need real-time email access
• ✅ Want full Gmail search capabilities
• ✅ Processing current/recent emails
• ✅ Need Gmail-specific metadata (labels, threads)

Use Mbox Import (Fallback) When:

• ✅ API credentials unavailable
• ✅ Processing archived/historical emails
• ✅ Working offline
• ✅ Migrating from other email systems
• ✅ Batch processing large email datasets

Requirements

google-api-python-client==2.108.0
google-auth-httplib2==0.1.1
google-auth-oauthlib==1.1.0
google-auth==2.23.4

Note: Mbox functionality uses Python's built-in mailbox module - no additional dependencies required.

Integration Examples

Opportunity Tracking Application

# Process emails for opportunity detection
def find_business_opportunities():
    client = GmailClient()
    
    # Try API first, fallback to mbox
    if client.authenticate():
        emails = client.search_emails("subject:(proposal OR contract OR meeting)")
    else:
        emails = client.search_mbox_emails('backup.mbox', 'proposal')
    
    opportunities = []
    for email in emails:
        if is_business_opportunity(email):
            opportunities.append(extract_opportunity_data(email))
    
    return opportunities

Troubleshooting

Gmail API Issues

• Ensure credentials.json is in the correct location
• Check Google Cloud Console for API quotas
• Verify OAuth consent screen is configured

Mbox Issues

• Ensure mbox file path is correct and accessible
• Large mbox files may take time to process
• Some email clients export in different mbox formats

Contributing

This Gmail client is designed as a modular component for broader applications. When extending functionality, maintain the unified data structure between API and mbox methods to ensure consistent integration patterns.