Gmail

A comprehensive Gmail integration plugin for Claude Code that enables multi-account email management through the Gmail API. Read, search, send, and organize emails directly from your Claude Code sessions.

Overview

The Gmail plugin provides a complete email management solution for Claude Code, supporting multiple Google accounts with features including:

• Multi-Account Support: Manage personal, work, and project-specific Gmail accounts
• Full Email Operations: List, read, send, reply, and organize emails
• Smart Caching: Local caching for optimized API usage
• Rate Limiting: Built-in quota management to prevent API throttling
• Batch Operations: Efficient bulk operations for label management and cleanup
• 5-Step Sending Workflow: Structured email composition with test sends and user confirmation

Features

Core Email Operations

• List and search emails with Gmail's powerful query syntax
• Read individual messages and entire threads
• Send new emails with plain text or HTML content
• Reply to existing conversations
• Attach files to outgoing emails
• Save emails as drafts

Organization & Management

• Create, update, and delete labels
• Mark messages as read/unread
• Star/unstar messages
• Archive and trash messages
• Batch modify labels across multiple messages

Advanced Features

• Local Caching: Reduces API calls by caching message lists and content
• Quota Management: Tracks usage against Gmail API limits (250 units/second)
• Exponential Backoff: Automatic retry with intelligent delays for rate limiting
• Batch Processing: Efficient bulk operations for high-volume tasks

Prerequisites

Before using this plugin, you need:

1. Python 3.10+ with uv package manager
2. Google Cloud Project with Gmail API enabled
3. OAuth 2.0 credentials (Desktop application type)

Required Google OAuth Scopes

• gmail.modify - Read, modify, and delete emails
• gmail.send - Send emails on behalf of the user
• gmail.labels - Manage email labels

Setup Guide

Step 1: Create Google Cloud Project

1. Go to Google Cloud Console
2. Click the project selector at the top and select "New Project"
3. Enter a project name (e.g., gmail-skill) and click "Create"

Step 2: Enable Gmail API

1. Navigate to "APIs & Services" > "Library" in the left menu
2. Search for "Gmail API"
3. Click the "Enable" button

Step 3: Configure OAuth Consent Screen

1. Go to "APIs & Services" > "OAuth consent screen"
2. Select "External" for User Type and click "Create"
3. Fill in the required fields:

• App name: Gmail Skill
• User support email: Your email address
• Developer contact: Your email address

1. Click "Save and Continue"
2. Add the following scopes:

• https://www.googleapis.com/auth/gmail.modify
• https://www.googleapis.com/auth/gmail.send
• https://www.googleapis.com/auth/gmail.labels

1. Add your Gmail address as a test user
2. Click "Save and Continue"

Step 4: Create OAuth Client ID

1. Go to "APIs & Services" > "Credentials"
2. Click "Create Credentials" > "OAuth client ID"
3. Select "Desktop app" as the application type
4. Enter a name (e.g., Gmail Skill Client)
5. Click "Create"
6. Download the JSON file

Step 5: Configure the Plugin

# Navigate to the skill directory
cd .claude/skills/gmail

# Move the downloaded credentials file
mv ~/Downloads/client_secret_*.json references/credentials.json

# Copy the default accounts configuration
cp assets/accounts.default.yaml accounts.yaml

# Edit accounts.yaml with your account information

Step 6: Authenticate Accounts

# Authenticate each account
uv run python scripts/setup_auth.py --account personal
uv run python scripts/setup_auth.py --account work

# Verify registered accounts
uv run python scripts/setup_auth.py --list

When the browser opens:

1. Log in to your Google account
2. If you see "This app isn't verified", click "Advanced" > "Continue"
3. Approve all permission requests