Gmail Label & Filter Organizer

# Gmail Label & Filter Organizer

Analyze your inbox to identify patterns, create a label hierarchy, and set up Gmail filters to auto-organize incoming mail.

## When to Use

- "Organize my Gmail inbox"
- "Set up filters for my newsletters and notifications"
- "Create labels to sort my email by project"
- Inbox has 500+ unread and needs a system

## Requirements

- **Google Cloud CLI** (`gcloud`) authenticated with Gmail API
- OAuth2 scopes: `gmail.labels`, `gmail.settings.basic`, `gmail.readonly`
- `jq` for JSON parsing

## Workflow

### Step 1 — Authenticate

```bash
ACCESS_TOKEN=$(gcloud auth print-access-token)
```

### Step 2 — Analyze Current Inbox Patterns

Fetch recent messages and analyze senders/subjects:

```bash
# Get last 100 inbox messages
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://gmail.googleapis.com/gmail/v1/users/me/messages?q=in:inbox&maxResults=100" | \
  jq -r '.messages[].id' > /tmp/gmail_msg_ids.txt

# Extract sender domains and subjects for pattern analysis
while read MSG_ID; do
  curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
    "https://gmail.googleapis.com/gmail/v1/users/me/messages/$MSG_ID?format=metadata&metadataHeaders=From&metadataHeaders=Subject" | \
    jq '{from: (.payload.headers[] | select(.name=="From") | .value), subject: (.payload.headers[] | select(.name=="Subject") | .value)}'
done < /tmp/gmail_msg_ids.txt > /tmp/gmail_analysis.json
```

### Step 3 — Identify Categories

Group emails by:
- **Sender domain** — newsletters, notifications, work domains, personal
- **Subject patterns** — invoices, receipts, automated alerts, meeting invites
- **Frequency** — daily digests, weekly reports

Present proposed label taxonomy to user:
```
📁 Work/
  📁 Work/ProjectAlpha
  📁 Work/ProjectBeta
📁 Newsletters/
📁 Finance/
  📁 Finance/Receipts
  📁 Finance/Invoices
📁 Notifications/
  📁 Notifications/GitHub
  📁 Notifications/Social
```

### Step 4 — Create Labels

After user approves the taxonomy:

```bash
# Create a label
curl -s -X POST -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Work/ProjectAlpha", "labelListVisibility": "labelShow", "messageListVisibility": "show"}' \
  "https://gmail.googleapis.com/gmail/v1/users/me/labels"
```

Repeat for each label in the hierarchy.

### Step 5 — Create Filters

For each category pattern:

```bash
# Create a filter (e.g., newsletters go to Newsletters label, skip inbox)
curl -s -X POST -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "criteria": {"from": "newsletter@example.com"},
    "action": {"addLabelIds": ["{LABEL_ID}"], "removeLabelIds": ["INBOX"]}
  }' \
  "https://gmail.googleapis.com/gmail/v1/users/me/settings/filters"
```

### Step 6 — Apply Labels to Existing Messages

Batch-modify existing messages matching the filter criteria:

```bash
# Find matching messages
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://gmail.googleapis.com/gmail/v1/users/me/messages?q=from:newsletter@example.com" | jq -r '.messages[].id'

# Batch modify
curl -s -X POST -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["msg1", "msg2"], "addLabelIds": ["{LABEL_ID}"], "removeLabelIds": ["INBOX"]}' \
  "https://gmail.googleapis.com/gmail/v1/users/me/messages/batchModify"
```

### Step 7 — Report

Provide summary: labels created, filters set, messages organized. Store the configuration in `outputs/gmail-organization-plan.md`.

## Important Rules

- Always show proposed labels and filters before creating them
- Never delete messages or existing labels without explicit confirmation
- Preserve existing label structure — add, don't replace

## Example Prompts

- "Organize my Gmail inbox by project"
- "Set up filters so newsletters skip inbox"
- "Create a label system for my freelance clients"