Skip to main content

Getting Started

This guide will help you set up the Email Assistant on your machine.

Prerequisites​

RequirementVersion
Python3.11+
Gmail AccountPersonal or Google Workspace
Google Cloud ProjectFor Gmail API
Gemini API KeyFor AI categorization

Installation​

1. Clone Repository​

git clone https://github.com/YOUR_USERNAME/emailAssistant.git
cd emailAssistant

2. Create Virtual Environment​

python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

3. Install Dependencies​

# Core dependencies
pip install -r requirements.txt

# For development and testing
pip install -r requirements-dev.txt

4. Configure Gmail API​

Create Google Cloud Project​

  1. Go to Google Cloud Console
  2. Create a new project
  3. Enable Gmail API
  4. Enable Google Calendar API (optional)
  5. Enable Google Tasks API (optional)

Create OAuth Credentials​

  1. Go to APIs & Services > Credentials
  2. Click Create Credentials > OAuth client ID
  3. Select Desktop app
  4. Download credentials.json
  5. Place in project root

5. Set Gemini API Key​

Get your key from Google AI Studio

export GOOGLE_API_KEY='your_api_key_here'

# Add to shell profile for persistence
echo 'export GOOGLE_API_KEY="your_api_key_here"' >> ~/.bashrc
source ~/.bashrc

6. Create Directories​

mkdir -p data/cache data/digest data/metrics data/test_results logs config

7. Configure Application​

cp config/config.example.json config/config.json

Edit config/config.json:

{
  "api_settings": {
    "gemini_model": "gemini-2.5-flash-lite",
    "requests_per_minute": 30,
    "max_retries": 3,
    "timeout_seconds": 30
  },
  "gmail_settings": {
    "max_emails_to_fetch": 10,
    "search_query": "is:unread newer_than:1d"
  },
  "cache_settings": {
    "enabled": true,
    "max_cached_emails": 30,
    "cache_expiry_hours": 24
  }
}

Running the Application​

First Run (CLI)​

python src/main.py

On first run, you'll be prompted to authenticate:

  1. Browser opens automatically
  2. Sign in with your Google account
  3. Grant permissions
  4. Token saved to token.json

Web Interface​

# Start the server
./scripts/start_server.sh
# or
python src/web/server.py

Open: http://localhost:8001

Project Structure​

emailAssistant/
├── src/
│   ├── main.py              # CLI entry point
│   ├── utils/               # Utility modules
│   │   ├── email_utils.py   # Gmail API operations
│   │   ├── gemini_utils.py  # Gemini AI operations
│   │   ├── display_utils.py # Digest generation
│   │   ├── logger_utils.py  # Logging configuration
│   │   └── metrics_utils.py # Metrics tracking (SQLite)
│   ├── core/                # Core modules
│   │   ├── config_manager.py
│   │   └── cache_manager.py
│   └── web/                 # Web interface
│       ├── server.py        # Flask server
│       ├── templates/       # HTML templates
│       └── static/          # CSS and JavaScript
├── config/
│   └── config.json          # Configuration
├── data/
│   ├── cache/               # Email cache
│   ├── digest/              # Digest data
│   └── metrics/             # SQLite database
├── logs/
│   └── email_assistant.log
├── tests/                   # Test suite
└── requirements.txt

Troubleshooting​

"No digest data available"​

Run the main script first:

python src/main.py

"Lock file stuck"​

If the "Refreshing..." button won't reset:

rm script.lock

"credentials.json not found"​

Download from Google Cloud Console and place in project root.

"GOOGLE_API_KEY not set"​

Export the environment variable:

export GOOGLE_API_KEY='your_key_here'

Port Conflict​

lsof -i :8001
kill -9 <PID>

Import Errors​

cd /path/to/emailAssistant
source .venv/bin/activate
pip install -r requirements.txt

Security Notes​

NEVER commit these files:

  • credentials.json - OAuth credentials
  • token.json - Access token
  • config/config.json - May contain sensitive data
  • data/ - Contains personal email data
  • .env - Environment variables

These are protected by .gitignore.

Next Steps​