aiagentwithdhruv/gmail-inbox

Gmail Inbox Management

Goal

Check and manage emails across multiple Gmail accounts using unified tooling.

Scripts

• ./scripts/gmail_unified.py - Check and manage inboxes
• ./scripts/gmail_multi_auth.py - Authenticate accounts
• ./scripts/gmail_bulk_label.py - Bulk labeling
• ./scripts/gmail_create_filters.py - Create filters
• ./scripts/gmail_auth.py - Auth helper

Quick Reference

# Check unread across all accounts
python3 ./scripts/gmail_unified.py --query "is:unread" --limit 50

# Check specific account only
python3 ./scripts/gmail_unified.py --query "is:unread" --account yourcompany

# List registered accounts
python3 ./scripts/gmail_unified.py --accounts

# Label and archive emails
python3 ./scripts/gmail_unified.py --query "from:notifications@" --label "Notifications" --archive

# Mark as read
python3 ./scripts/gmail_unified.py --query "from:noreply@" --mark-read

# Dry run (preview)
python3 ./scripts/gmail_unified.py --query "subject:invoice" --label "Invoices" --dry-run

Account Registry

| Account | Email | Credentials | Token | |---------|-------|-------------|-------| | youruser | [email protected] | credentials.json | token_youruser.json | | yourcompany | [email protected] | credentials_yourcompany.json | token_yourcompany.json |

Troubleshooting Auth Errors

"Token file not found"

python3 ./scripts/gmail_multi_auth.py --account yourcompany --email [email protected]

"invalid_scope: Bad Request"

rm token_youruser.json
python3 ./scripts/gmail_multi_auth.py --account youruser --email [email protected]

"Failed to authenticate" Check that credentials.json exists in root directory.

Required Scopes

• gmail.modify - Read/write emails
• gmail.labels - Create/manage labels
• gmail.settings.basic - Manage settings
• spreadsheets - Google Sheets access
• drive - Google Drive access

Credentials Location

All credential files should be in the workspace root:

• credentials.json / credentials_yourcompany.json - OAuth client configs
• token_*.json - Auth tokens (auto-generated)
• gmail_accounts.json - Account registry

---

Schema

Inputs

| Name | Type | Required | Description | |------|------|----------|-------------| | query | string | No | Gmail search query (e.g., 'is:unread') | | account | string | No | Specific account name from registry | | limit | integer | No | Max emails to fetch (default: 50) |

Outputs

| Name | Type | Description | |------|------|-------------| | emails | array | List of email objects with subject, from, date, snippet |

Credentials

| Name | Source | |------|--------| | credentials.json | file | | token_*.json | file (auto-generated) |

Composable With

Skills that chain well with this one: gmail-label, instantly-autoreply

Cost

Free (Gmail API)