Configuration & API Setup

Gmail Cleanup — Configuration & API Setup
Gmail Cleanup — Practical Scripting
Course 1 · Chapter 1 · Configuration & API Setup

⚙️ Configuration & API Setup

Before you can access Gmail from Python, you need to set up the Gmail API and create authentication credentials. This chapter walks you through the complete setup process: creating a Google Cloud project, obtaining API credentials, and organizing your project structure for secure credential management.

📋 Overview

To interact with Gmail from Python, you need:

  1. A Google Cloud project (free tier available)
  2. Gmail API enabled in that project
  3. OAuth 2.0 credentials (client ID and secret)
  4. Python libraries installed
  5. Secure credential storage

🔧 Step-by-Step Setup

Step 1: Create a Google Cloud Project

1. Go to Google Cloud Console
2. Click "Create Project" in the top-left dropdown
3. Enter project name: "Gmail Cleanup Utility"
4. Click "Create" and wait for it to be created (2-3 minutes)

Step 2: Enable the Gmail API

1. In the Cloud Console, go to "APIs & Services" → "Library"
2. Search for "Gmail API"
3. Click on it and press "Enable"
4. Wait for the API to be enabled (30 seconds)

Step 3: Create OAuth 2.0 Credentials

1. Go to "APIs & Services" → "Credentials"
2. Click "Create Credentials" → "OAuth client ID"
3. Select "Desktop application"
4. Click "Create" and download the JSON file
5. Save it as credentials.json in your project

📁 Project Structure

Organize your Gmail cleanup project like this:

gmail-cleanup/ ├── .env ← Gmail account email (loaded at runtime) ├── .env.example ← Template for .env ├── credentials.json ← Google OAuth credentials (from Step 3) ├── token.json ← Generated after first auth (gitignore this!) ├── requirements.txt ← Python dependencies ├── gmail_utils.py ← Gmail utility functions ├── cleanup.py ← Main cleanup script ├── .gitignore ← Don't commit secrets! └── tests/ └── test_gmail_utils.py
🔒 CRITICAL: Never commit credentials.json or token.json to Git! Add them to .gitignore.

📦 Python Dependencies

Create requirements.txt:

google-auth-oauthlib==1.1.0 google-auth-httplib2==0.2.0 google-api-python-client==2.100.0 python-dotenv==1.0.0

Install them:

pip install -r requirements.txt

🔐 Understanding OAuth 2.0

Gmail API uses OAuth 2.0 for secure authentication. Here's how it works:

  1. First Run: User visits Google login page (browser opens automatically)
  2. Grant Access: User clicks "Allow" to grant your app access to Gmail
  3. Token Saved: Python saves access token to token.json
  4. Future Runs: Script reads token from file, no login needed (until token expires)
💡 Key Concept

You only need to authorize once! After that, the script can access Gmail without manual login.

🔧 Configuration File Setup

Create .env.example (template for users):

# Gmail account to manage GMAIL_USER=your-email@gmail.com # API settings API_REQUEST_TIMEOUT=10 MAX_RESULTS=100 # Cleanup settings DELETE_OLDER_THAN_DAYS=365 MIN_ATTACHMENT_SIZE_MB=10

Create .env with your actual values (don't commit this!):

GMAIL_USER=emubantam@gmail.com API_REQUEST_TIMEOUT=10 MAX_RESULTS=100 DELETE_OLDER_THAN_DAYS=365 MIN_ATTACHMENT_SIZE_MB=10

⚠️ Common Setup Issues

Issue 1: "Gmail API has not been used in project"

Solution: Make sure you enabled the Gmail API in Step 2. Give it 30 seconds to activate.

Issue 2: "Credentials file not found"

Solution: Make sure credentials.json is in the same folder as your Python script.

Issue 3: "2-factor authentication enabled"

Solution: Gmail requires 2FA. This is good for security! The OAuth flow handles it.

💻 Coding Challenges

Challenge 1: Project Setup

Set up the complete project structure:

  1. Create gmail-cleanup/ directory
  2. Create .env and .env.example files
  3. Create requirements.txt with Gmail API dependencies
  4. Create credentials.json from Google Cloud Console
  5. Create .gitignore with appropriate entries

Goal: Complete the setup without errors.

→ Solution

Challenge 2: Install Dependencies

Install and verify Python dependencies:

  1. pip install -r requirements.txt
  2. Create a test script that imports all libraries
  3. Print library versions to verify installation

Goal: Verify all dependencies are correctly installed.

→ Solution

Challenge 3: OAuth Authentication

Create a script that performs initial OAuth setup:

  1. Read credentials.json
  2. Perform OAuth flow (opens browser)
  3. Save token.json for future use
  4. Verify that token.json was created

Goal: Understand and complete the OAuth authentication flow.

→ Solution

🎯 What's Next

Chapter 2 will teach you how to load and manage configuration securely with environment variables and .env files, then Chapter 3 will connect to the Gmail API and start querying your mailbox.