Gmail Auto-Label

Goal

Fetch inbox emails, classify them via parallel subagents into Action Required / Waiting On / Reference, and apply labels in bulk via Gmail API.

Scripts

•./scripts/gmail_label_fetch.py - Fetch email summaries as compact JSON
•./scripts/gmail_label_split.py - Split emails into N chunks for parallel classification
•./scripts/gmail_label_merge.py - Merge classified chunks into single labels.json
•./scripts/gmail_label_apply.py - Apply label classifications in bulk

Subagent

•email-classifier — defined in .claude/agents/email-classifier.md
•Model: Sonnet 4.5 (fast, cost-efficient classification)
•Each subagent reads one chunk, writes one classified output file

Flow (Parallel — default)

Step 1: Fetch emails

bash

python3 .claude/skills/gmail-label/scripts/gmail_label_fetch.py \
  --account ACCOUNT --query "in:inbox" --limit 100 --output .tmp/emails.json

Step 2: Split into chunks

bash

python3 .claude/skills/gmail-label/scripts/gmail_label_split.py \
  --input .tmp/emails.json --chunks 10 --output-dir .tmp/chunks

Step 3: Classify in parallel (spawn 10 subagents)

Spawn 10 email-classifier subagents in background, one per chunk. Each subagent:

•Reads .tmp/chunks/chunk_N.json
•Classifies each email
•Writes .tmp/chunks/classified_N.json

Use the Task tool with run_in_background: true and model: "sonnet". Launch ALL 10 in a single message for true parallelism:

code

For each chunk 0-9, spawn a Task with:
  subagent_type: "email-classifier"
  model: "sonnet"
  run_in_background: true
  prompt: "Read /absolute/path/.tmp/chunks/chunk_N.json, classify each email, write results to /absolute/path/.tmp/chunks/classified_N.json"

CRITICAL: Do NOT use TaskOutput to read subagent results. The subagents write their results to files — the main agent never needs to see the classification data. Reading TaskOutput will flood the context window and cause "prompt too long" errors with large batches (500+ emails).

Instead, poll for file existence:

bash

# Wait until all classified files exist (timeout after 120s)
for i in $(seq 0 9); do
  while [ ! -f ".tmp/chunks/classified_$i.json" ]; do sleep 2; done
done

Then proceed directly to Step 4 (merge).

Step 4: Merge classifications

bash

python3 .claude/skills/gmail-label/scripts/gmail_label_merge.py \
  --input-dir .tmp/chunks --output .tmp/labels.json

Step 5: Apply labels

bash

python3 .claude/skills/gmail-label/scripts/gmail_label_apply.py \
  --account ACCOUNT --input .tmp/labels.json

Classification Guidelines

Action Required:

•Security alerts that need verification
•Expiring credit cards / domain renewals with deadlines
•Slack @mentions asking questions
•New team members to greet (Slack join notifications)
•Client emails needing response
•Business listing updates (Google Business Profile, Bing Places)
•Stripe action-required notices

Waiting On:

•Outbound sales emails awaiting reply
•Support tickets awaiting resolution
•Proposals sent, pending response

Reference:

•Marketing newsletters (DigitalMarketer, etc.)
•Charity/nonprofit newsletters (RAPS, etc.)
•Google Business Profile performance reports
•Promotional offers (Blinkist, sales, etc.)
•Platform update notifications (Google Play, Apify, etc.)
•Confirmation codes (already used)
•Real estate newsletters (Westbank, etc.)
•Gaming account emails (Riot Games, etc.)
•Informational security alerts (2FA turned on, etc.)
•Health advisories
•Legal/policy update notices

Account Registry

Accounts are stored in gmail_accounts.json at workspace root. Each account needs:

•email - Gmail address
•token_file - Path to OAuth token

Adding New Accounts

bash

python3 .claude/skills/gmail-inbox/scripts/gmail_multi_auth.py --account ACCOUNT_NAME --email EMAIL

Performance

•Serial flow: ~36s for 100 emails (fetch 1s + classify 34s + apply 1s)
•Parallel flow: ~30s for 100 emails (classify 19s + merge <1s + apply ~10s)
•Classification is the bottleneck; 10 parallel subagents cut it from 34s to 19s (~1.8x speedup)
•Agent startup overhead (~4s stagger) limits theoretical gains
•Apply step may vary due to Gmail API throttling