GWS Gmail Auto

Automate Gmail operations for email management, filtering, labeling, and batch processing.

When to Use This Command

Run this command when you need to:

• Process emails in bulk: archive, label, delete, or move messages matching specific criteria
• Set up or manage Gmail filters and labels programmatically across your domain
• Export email data for compliance, backup, or migration to another platform

Consider alternatives when:

• You need to compose and send a single email which is simpler through the Gmail interface
• You are managing Gmail delegated access which requires Admin Console configuration

Quick Start

Configuration

Copy
name: gws-gmail-auto
type: command
category: google-workspace

Example Invocation

Copy
claude command:run gws-gmail-auto --action cleanup --filter "older:90d label:promotions" --apply archive

Example Output

Executing Gmail automation...
  Action: cleanup
  Filter: older:90d label:promotions
  Operation: archive

Scanning inbox...
  Messages matching filter: 1,247
  Total size: 845 MB

Processing messages...
  [========================================] 1247/1247 complete

Cleanup summary:
  Archived: 1,247 messages
  Storage freed: 845 MB
  Remaining in Promotions: 89 messages (last 90 days)

Labels updated: Promotions (1,247 messages removed from inbox view)

Core Concepts

Gmail Automation Overview

Aspect	Details
Bulk Actions	Archive, delete, label, star, mark-read on messages matching criteria
Filters	Create, update, delete Gmail filters for automatic message processing
Labels	Manage labels: create, rename, delete, nest with color customization
Export	Download messages in EML or MBOX format for backup or migration
Search	Full Gmail search syntax support for precise message targeting

Automation Workflow

Define Filter Criteria
        |
        v
Preview Matching Messages
  (count + sample)
        |
        v
Select Bulk Action
  |      |       |       |
  v      v       v       v
Archive Delete  Label   Export
  |      |       |       |
  v      v       v       v
Process in Batches
  [progress tracking]
        |
        v
Report Results

Configuration

Parameter	Type	Default	Description
action	string	(required)	Operation: cleanup, filter, label, export, search
filter	string	(none)	Gmail search query to select target messages
apply	string	(none)	Bulk action: archive, delete, label, star, mark-read
label	string	(none)	Label name for label operations or label-based filtering
export-path	string	./	Local directory for message export output

Best Practices

1. Preview before processing - Always run with --dry-run first to see how many messages match your filter. A broad filter like older:30d might match thousands of important messages.

2. Use Gmail search syntax precisely - Combine operators for precise targeting: from:[email protected] subject:newsletter older:60d is much safer than subject:newsletter alone.

3. Archive instead of delete - Archiving removes messages from the inbox without deleting them. This is safer for cleanup operations since archived messages are still searchable.

4. Create filters for ongoing automation - Instead of repeatedly running cleanup commands, create a Gmail filter that automatically archives, labels, or deletes matching messages going forward.

Common Issues

1. Batch processing interrupted - Network timeouts can interrupt large batch operations. The command tracks progress and can resume from where it left off using the batch checkpoint file.

2. Filter matches unexpected messages - Gmail search syntax can be surprising. The operator from:user matches any header containing "user", not just the from address. Use from:[email protected] for precision.

3. Export exceeds disk space - Large mailboxes can produce multi-gigabyte exports. Check available disk space before starting and use date filters to export in smaller chunks. Consider exporting in MBOX format which is more compact than individual EML files for large mailbox archives.