Email Processor

Email Processor

Automates Gmail inbox triage by categorizing unread emails and marking low-priority items as read.

What It Does

1. Fetches all unread emails
2. Identifies marketing, newsletters, promotions, and news
3. Marks low-priority emails as read
4. Surfaces important emails (GitHub, security alerts, direct communications)
5. Generates a summary report

Prerequisites

1. Install gog CLI

brew install steipete/tap/gogcli

Verify installation:

gog --version

2. Google Cloud OAuth Setup

1. Go to Google Cloud Console
2. Create a new project (or use existing)
3. Enable the Gmail API:
   • Navigate to "APIs & Services" > "Library"
   • Search for "Gmail API" and enable it
4. Create OAuth credentials:
   • Go to "APIs & Services" > "Credentials"
   • Click "Create Credentials" > "OAuth client ID"
   • Select "Desktop app" as application type
   • Download the JSON file

3. Authenticate gog

# Set credentials
gog auth credentials /path/to/client_secret.json

# Add your Gmail account
gog auth add your@gmail.com --services gmail

# Verify
gog auth list

Usage

Quick Process

bash ~/.openclaw/workspace/skills/email-processor/scripts/process-emails.sh

Manual Processing (via Codex)

1. Fetch unread emails:

   gog gmail search 'is:unread' --json --max 100
   

2. Mark specific thread as read:

   gog gmail thread modify <thread-id> --remove UNREAD --force
   

3. Mark marketing emails (batch):

   gog gmail search 'is:unread' --json --max 100 | \
     jq -r '.threads[] | select(.labels | contains(["CATEGORY_PROMOTIONS"])) | .id' | \
     while read id; do gog gmail thread modify "$id" --remove UNREAD --force; done
   

Email Categories

Auto-Marked as Read

• CATEGORY_PROMOTIONS - Promotional emails
• [Superhuman]/AI/News - Newsletters
• [Superhuman]/AI/Marketing - Marketing emails
• [Superhuman]/AI/Pitch - Cold outreach/pitches
• [Superhuman]/AI/AutoArchived - Auto-categorized low priority

Preserved (Important)

• GitHub notifications (PRs, issues, security alerts)
• Direct personal communications
• Financial/transaction emails
• Security alerts
• Calendar invites

Verification

Check setup is working:

# Test gog connectivity
gog gmail search 'is:unread' --max 5

# Check account
gog auth list

# Test modify (dry run - just list what would be marked)
gog gmail search 'is:unread' --json --max 10 | \
  jq -r '.threads[] | select(.labels | contains(["CATEGORY_PROMOTIONS"])) | {id: .id, subject: .subject}'

Troubleshooting

Labels Reference

Gmail automatically applies these labels:

• CATEGORY_PERSONAL - Personal emails
• CATEGORY_SOCIAL - Social notifications
• CATEGORY_PROMOTIONS - Promotions
• CATEGORY_UPDATES - Updates/notifications
• CATEGORY_FORUMS - Forum messages
• IMPORTANT - Marked important
• UNREAD - Unread status

Superhuman AI labels (if using Superhuman):

• [Superhuman]/AI/News - Newsletters
• [Superhuman]/AI/Marketing - Marketing
• [Superhuman]/AI/Pitch - Pitches
• [Superhuman]/AI/AutoArchived - Auto-archived