gmaillm

LLM-friendly Gmail API wrapper with CLI and progressive disclosure patterns.

Installation

Recommended: Using Makefile (Easiest)

For the simplest installation with automatic setup:

cd /path/to/gmaillm

# Install globally and setup shell completion
make install
make verify
make install-completion

See make help for all available targets.

Alternative: Manual Installation

cd /path/to/gmaillm
pip3 install --break-system-packages -e .

With Shell Completion (Recommended)

For faster typing with tab-completion support:

# 1. Install the package
pip3 install --break-system-packages -e .

# 2. Install shell completions
gmail --install-completion

# 3. Restart your shell
exec $SHELL

Note: After running --install-completion, you'll see a message confirming the completion script was installed. Restart your shell to activate it.

Supported Shells

• bash - Uses ~/.bash_completion.d/ or ~/.bashrc
• zsh - Uses ~/.zshrc or completion directory
• fish - Uses ~/.config/fish/completions/
• PowerShell - Uses profile completion directory

Setup & Authentication

Configuration Locations

gmaillm automatically detects whether it's running as a plugin or standalone:

• Plugin mode (when CLAUDE_PLUGIN_ROOT is set):

  • Config: ${CLAUDE_PLUGIN_ROOT}/credentials/
  • OAuth keys: ${CLAUDE_PLUGIN_ROOT}/credentials/oauth-keys.json
  • Credentials: ${CLAUDE_PLUGIN_ROOT}/credentials/credentials.json

• Standalone mode (default):

  • Config: ~/.gmaillm/
  • OAuth keys: ~/.gmaillm/oauth-keys.json
  • Credentials: ~/.gmaillm/credentials.json

First Time Setup

1. Obtain OAuth2 credentials from Google Cloud Console:

   • Go to Google Cloud Console
   • Create OAuth2 Client ID (Application type: Desktop app)
   • Download the credentials as oauth-keys.json
   • Save to one of these locations:
     • ~/.gmaillm/oauth-keys.json (recommended for standalone)
     • ${CLAUDE_PLUGIN_ROOT}/credentials/oauth-keys.json (for plugin use)
     • ~/Desktop/OAuth2/gcp-oauth.keys.json (fallback)

2. Authenticate with Gmail:

   gmail setup-auth
   

   This will:

   • Open your browser for Google authentication
   • Save credentials to the appropriate location (plugin or standalone)
   • Configure Gmail API access

3. Verify setup:

   gmail verify
   

Troubleshooting

If you see "Credentials file is empty" error:

# Run authentication setup
python3 -m gmaillm.setup_auth

# If port 8080 is in use, specify a different port
python3 -m gmaillm.setup_auth --port 8081

If you see "Address already in use" error:

# Kill any existing auth processes
pkill -f "gmaillm.setup_auth"

# Try a different port
python3 -m gmaillm.setup_auth --port 9999

Quick Start

CLI Usage

# Verify setup
gmail verify

# List emails
gmail list
gmail list --folder SENT --max 5

# Read email
gmail read <message_id>
gmail read <message_id> --full

# View thread
gmail thread <message_id>

# Search
gmail search "from:example@gmail.com has:attachment"

# Reply
gmail reply <message_id> --body "Thanks for the update!"

# Send
gmail send --to user@example.com --subject "Test" --body "Hello"

# List folders
gmail folders

# Manage labels
gmail label list          # List all labels (system and custom)
gmail label create MyLabel # Create a new label

# Manage email styles
gmail styles list                    # List all email styles
gmail styles show professional-formal # View a specific style
gmail styles create my-style         # Create a new style
gmail styles validate my-style       # Validate style format
gmail styles validate-all --fix      # Validate and auto-fix all styles

Email Styles

gmaillm supports a flexible email style system that allows you to define different writing styles for various contexts. Each style includes templates, formatting guidelines, and usage patterns.

Style Commands

# List all styles
gmail styles list

# View a specific style
gmail styles show professional-formal

# Create a new style (opens editor)
gmail styles create my-new-style

# Edit an existing style (opens editor)
gmail styles edit casual-friend

# Delete a style
gmail styles delete old-style
gmail styles delete old-style --force  # Skip confirmation

# Validate style format
gmail styles validate my-style
gmail styles validate my-style --fix   # Auto-fix formatting issues

# Validate all styles
gmail styles validate-all
gmail styles validate-all --fix        # Auto-fix all styles

Style Format

Each style file uses YAML frontmatter and XML-like sections:

---
name: "Style Name"
description: "When to use: Context description with usage guidance."
---

<examples>
Example email 1
---
Example email 2
</examples>

<greeting>
- "Hi [Name],"
- "Hello [Name],"
</greeting>

<body>
- Writing guideline 1
- Writing guideline 2
</body>

<closing>
- "Best,"
- "Thanks,"
</closing>

<do>
- What to do
- Best practices
</do>

<dont>
- What to avoid
- Common mistakes
</dont>

Required sections (in strict order):

1. examples - Example emails showing the style in action
2. greeting - Greeting patterns and guidelines
3. body - Body content guidelines
4. closing - Closing patterns
5. do - Best practices
6. dont - Things to avoid

See STYLES.md for complete style guide documentation.

Workflows

Interactive Workflows

Process emails interactively with prompts for each action:

# Run named workflow
gmail workflows run clear

# Run with custom query
gmail workflows run --query "is:unread from:boss@example.com"

LLM-Friendly Workflows (Programmatic)

Process emails programmatically with continuation tokens for automation:

# Start workflow (returns JSON with token + first email)
gmail workflows start clear

# Continue with actions (returns next email + same token)
gmail workflows continue <token> archive
gmail workflows continue <token> skip
gmail workflows continue <token> reply --reply-body "Thanks!"
gmail workflows continue <token> view    # View full body
gmail workflows continue <token> quit    # End workflow

JSON Response:

{
  "success": true,
  "token": "abc123...",
  "email": { /* full email data */ },
  "message": "Archived",
  "progress": {"total": 10, "processed": 3, "remaining": 7, "current": 4},
  "completed": false
}

Automation Example:

# Archive all unread emails
TOKEN=$(gmail workflows start clear | jq -r '.token')
while [ "$TOKEN" != "null" ]; do
  RESULT=$(gmail workflows continue "$TOKEN" archive)
  TOKEN=$(echo "$RESULT" | jq -r '.token')
done

Workflow Management

gmail workflows list              # List configured workflows
gmail workflows show clear        # View workflow details
gmail workflows create daily \
  --query "is:unread" \
  --auto-mark-read                # Create new workflow
gmail workflows cleanup           # Remove expired states

Python Library

from gmaillm import GmailClient

client = GmailClient()

# List emails
result = client.list_emails(folder='INBOX', max_results=10)
print(result.to_markdown())

# Read email
email = client.read_email(message_id, format="summary")
print(email.to_markdown())

Tips & Tricks

Speed Up Typing with Completions

Once you've installed shell completions (gmail --install-completion), you can:

• Type gmail l and press <TAB> → expands to available commands
• Type gmail send --to user and press <TAB> → shows field completions
• Type gmail and press <TAB> → shows all available commands

Quick Command Reference

# Most common commands
gmail verify                              # Check if setup is working
gmail status                              # See your inbox status
gmail list                                # Show recent emails
gmail search "from:someone@example.com"  # Find specific emails
gmail send --to user@example.com \
  --subject "Hello" --body "Hi there"    # Send an email

Help for Any Command

# Get help for a specific command
gmail send --help
gmail search --help

Documentation

User Guides

• Email Styles Guide - Creating and managing email writing styles
• Email Groups Guide - Managing email distribution groups

Technical Documentation

• Testing Guide - Running and writing tests
• API Reference - Complete API documentation
• Changelog - Version history and changes

Testing

make test                 # Run full test suite with coverage
uv run pytest tests/      # Run tests directly