104 lines
4.1 KiB
Markdown
104 lines
4.1 KiB
Markdown
# 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
|
|
```bash
|
|
# 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
|
|
```go
|
|
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 |