gmail/CLAUDE.md

CLAUDE.md - Gmail Inbox Analyzer Project Guide

Project Overview

This is a Gmail Inbox Analyzer - a Go application that fetches email metadata (sender, subject, date, message ID) from a Gmail inbox using the Gmail API. The tool outputs data in CSV or JSON format for organization and analysis purposes.

Architecture & Structure

• Single binary application (main.go) - no complex module structure
• OAuth2 authentication with Google's Gmail API
• Command-line interface with three required arguments
• Two output formats: CSV and JSON
• No persistent storage - credentials are not stored locally

Key Files

• /Users/orejav/repos/mail-automation/main.go - Main application code (155 lines)
• /Users/orejav/repos/mail-automation/go.mod - Go module definition with Gmail API dependencies
• /Users/orejav/repos/mail-automation/go.sum - Dependency checksums
• /Users/orejav/repos/mail-automation/README.md - User documentation and setup instructions

Dependencies & Tech Stack

• Go 1.21 (minimum version)
• golang.org/x/oauth2 - OAuth2 authentication
• google.golang.org/api/gmail/v1 - Gmail API client
• Standard library: encoding/csv, encoding/json, net/http, context

Development Commands

# Install/update dependencies
go mod tidy

# Run the application (requires Google OAuth credentials)
go run main.go <CLIENT_ID> <CLIENT_SECRET> <csv|json>

# Example usage
go run main.go "123456789-abc.apps.googleusercontent.com" "GOCSPX-your_secret" csv > emails.csv
go run main.go "123456789-abc.apps.googleusercontent.com" "GOCSPX-your_secret" json > emails.json

# Build binary
go build -o gmail-analyzer main.go

Authentication Flow

1. Application generates OAuth2 URL for Gmail readonly access
2. User visits URL in browser and authorizes access
3. User copies authorization code from browser
4. User pastes code into terminal
5. Application exchanges code for access token
6. Token is used for API calls (not persisted)

Core Components

1. main() - CLI argument parsing and orchestration
2. getClient() - OAuth2 authentication flow
3. fetchEmails() - Gmail API pagination and message retrieval
4. parseMessage() - Extract metadata from Gmail message headers
5. outputCSV() / outputJSON() - Data formatting and output

Data Structure

type EmailInfo struct {
    Sender  string `json:"sender"`
    Subject string `json:"subject"`
    Date    string `json:"date"`
    ID      string `json:"id"`
}

Google Cloud Setup Required

• Google Cloud Console project
• Gmail API enabled
• OAuth 2.0 Client ID (Desktop application type)
• Client ID and Client Secret credentials

API Limitations & Behavior

• Uses Gmail API readonly scope: gmail.GmailReadonlyScope
• Fetches emails from inbox only (in:inbox query)
• Processes all emails with pagination (no date/count limits)
• Rate limiting handled by Google's client library
• No email content/body is fetched - headers only

Common Tasks for Claude

1. Modify output format - Edit outputCSV() or outputJSON() functions
2. Add filtering - Modify Gmail query in fetchEmails() function
3. Add new metadata fields - Update EmailInfo struct and parseMessage()
4. Error handling improvements - Add retry logic or better error messages
5. Configuration - Add config file support or environment variables
6. Batch processing - Add date range or count limits

Testing & Debugging

• No unit tests currently exist
• Manual testing requires valid Google OAuth credentials
• Debug by checking Gmail API quotas in Google Cloud Console
• Common issues: invalid credentials, API not enabled, rate limiting

Security Considerations

• OAuth credentials passed as command-line arguments (visible in process list)
• No credential persistence (security by design)
• Readonly Gmail access only
• Consider environment variables for credentials in production use

Extension Points

• Add support for other Gmail folders/labels
• Implement credential caching (with proper security)
• Add filtering by date range, sender, or subject patterns
• Export to other formats (Excel, database)
• Add email content analysis capabilities