Gmail Filter

Gmail Filter Manager

Create and manage native Gmail filters for automatic email organization.

Commands

Create Filter

Syntax: /gmail-filter create <from-pattern> <label> [--archive]

Examples:

/gmail-filter create @newsletter.com Newsletters
/gmail-filter create @github.com Notifications --archive
/gmail-filter create "orders@amazon" Shopping

List Filters

Syntax: /gmail-filter list

Shows all existing filters with their criteria and actions.

Delete Filter

Syntax: /gmail-filter delete <filter-id>

Create Filter Workflow

Step 1: Parse Arguments

Extract from $ARGUMENTS:

• from_pattern - Email pattern (domain or address)
• label_name - Label to apply
• archive - Whether to remove from inbox

Step 2: Ensure Label Exists

Check if label exists, create if needed:

# List existing labels
gog gmail labels list --json

# Create if not found
gog gmail labels create "LabelName"

Step 3: Create the Filter

gog gmail filters create \
  --from "pattern@domain.com" \
  --add-label "LABEL_ID" \
  [--remove-label "INBOX"]

Note: Use label ID, not name, for the filter command.

Step 4: Verify Creation

gog gmail filters list --json

Confirm the filter appears in the list.

Step 5: Report Success

## Filter Created Successfully

**Criteria**: Emails from `@newsletter.com`
**Action**: Apply label "Newsletters"
**Archive**: Yes (removes from inbox)

This filter is now active and will automatically process matching emails.

**Note**: Existing emails are not affected. Use `/gmail-label apply` to label past emails.

List Filters Workflow

gog gmail filters list --json

Format output as table:

Delete Filter Workflow

gog gmail filters delete <filter-id>

Confirm deletion:

Filter `abc123` deleted successfully.

Filter Criteria Options

Available criteria (combine as needed):

• --from - Sender address or domain
• --to - Recipient address
• --subject - Subject contains
• --query - Full Gmail search query
• --has-attachment - Has attachments

Filter Actions

Available actions:

• --add-label - Apply a label (use label ID)
• --remove-label - Remove a label (use "INBOX" to archive)
• --forward - Forward to verified address
• --mark-read - Mark as read

Common Filter Recipes

Newsletter Filter (archive)

gog gmail filters create --from "@substack.com" --add-label "Newsletters" --remove-label "INBOX"

GitHub Notifications

gog gmail filters create --from "@github.com" --add-label "GitHub"

Shopping Orders

gog gmail filters create --from "orders@amazon" --add-label "Shopping/Orders"

Error Handling

• Label not found: Create it automatically
• Invalid filter criteria: Show supported options
• Duplicate filter: Warn user, don't create duplicate
• Permission error: Check OAuth scopes