google-email

Google Email Management

Manage Gmail sync, AI-powered triage, and email analysis workflows.

Prerequisites

Use the google-account-setup skill to configure Gmail accounts before using these workflows. Accounts must have OAuth credentials (has_credentials: true) for sync and triage to work.

Scripts

The scripts/ directory contains executable wrappers for all API endpoints. Always use these scripts instead of raw curl commands.

Run scripts using their full path relative to this skill's base directory (provided when the skill is loaded). For example: <skill-base-dir>/scripts/accounts

All scripts default to http://localhost:2529. Override with CLAUDE_ASSIST_SERVER env var.

Available scripts: accounts, sync-emails, emails, email, email-stats, triage, triage-progress

Workflow States

Emails progress through a three-state pipeline:

discovered - Listed from Gmail API but content not yet fetched
new - Full content fetched, ready for AI triage
triaged - Analysis complete with EmailAnalysis populated

Automated Schedule

The server runs these scheduled tasks automatically:

Incremental sync: Every 5 minutes (fetches new emails)
Batch triage: Every 5 minutes (requires ANTHROPIC_API_KEY)
Full sync: Daily at 4 AM (complete re-sync for consistency)

Email Analysis Structure

Each triaged email has an analysis field with this structure:

interface EmailAnalysis {
  overview: string;                    // 1-2 sentence summary
  mentioned_people: string[];          // Names mentioned in email
  mentioned_organizations: string[];   // Organizations mentioned
  potential_action_items: string[];    // Action items for recipient
  sender_type: 'automated' | 'human';
  message_type: 'spam' | 'newsletter' | 'alert' | 'group' | 'personal';
  unsubscribe_link: string | null;     // Extracted unsubscribe URL
  rationale: string;                   // Explanation of classification
}

Sender Type

automated: System-generated, no human composed (receipts, alerts, notifications, auto-responders)
human: Human composed, regardless of sending tool (CRM, ticketing system, etc.)

Message Type

spam: Unsolicited email confidently recognized as spam (phishing, scams, suspicious cold outreach). NOT newsletters.
newsletter: Any email with an unsubscribe link (periodic updates, marketing, announcements). Legitimacy determined later.
alert: System notifications, transactional (receipts, confirmations, calendar). No unsubscribe link typical.
group: Sent to mailing list or large recipient list, not individually addressed. Check TO/CC fields.
personal: Direct person-to-person, individually addressed in TO with small/relevant CC.

Multi-Turn Analysis

The AI triage uses a conversational approach:

Turn 1: Initial analysis with automatic JSON retry on parse error
Turn 2 (conditional): If classified as newsletter but missing unsubscribe link, HTML body is examined to extract the link

API Endpoints

Check Account Status

scripts/accounts

Returns accounts with email_sync_status and email_triage_status showing real-time progress.

Sync Operations

# Incremental sync all accounts
scripts/sync-emails

# Full sync specific account
scripts/sync-emails --account personal --full

Query Emails

# Filter by workflow status and message type
scripts/emails --status triaged --type newsletter --days 7

# Get single email with full details
scripts/email 123

# Get statistics
scripts/email-stats --days 7

Query Parameters:

account - Filter by account identifier (e.g., "personal", "work")
workflow_status - Filter by state: discovered, new, triaged
message_type - Filter by classification (comma-separated for OR): spam, newsletter, alert, group, personal
search - Full-text search on email content
with - Comma-separated substrings to match against from/to fields (OR logic). e.g. --with "alice,bob" finds emails from or to either person
days - Look back N days (default: 30)
limit - Results per page (default: 50, max: 100)
offset - Pagination offset

Triage Operations

# Batch triage all 'new' emails
scripts/triage

# Triage single email
scripts/triage 123

# Check progress
scripts/triage-progress

Common Workflows

1. Initial Sync After Account Setup

scripts/sync-emails --account personal --full
scripts/accounts  # monitor progress

2. Check Inbox Status

scripts/email-stats --days 7
scripts/triage-progress

3. Find Newsletters for Review

scripts/emails --type newsletter --status triaged --days 7

4. Find Personal Emails Needing Attention

scripts/emails --type personal --status triaged --days 3

5. Find Emails with Action Items

Query triaged emails and filter by those with potential_action_items in the analysis:

scripts/emails --status triaged --days 7

Then filter results where analysis.potential_action_items is non-empty.

6. Manual Triage Trigger

scripts/triage          # all pending
scripts/triage 123      # specific email