How to Clean Up Gmail Inbox with Claude Code and Google Workspace CLI

Mar 11, 2026

Problem

My Gmail inbox had thousands of emails. I tried manual cleanup but gave up after an hour. Traditional filters didn’t help because I couldn’t define precise rules for what to keep or delete.

I needed a smarter approach. Something that could understand the content of my emails, identify patterns, and help me make bulk decisions without accidentally deleting important messages.

What I Tried First

I started with Gmail’s built-in filters. But I ran into problems:

from:newsletter@ - didn't catch all newsletters
subject:unsubscribe - missed many promotional emails
older_than:1y - too broad, might delete important old emails

Each filter either missed too many emails or was too aggressive. I also tried Gmail’s “Select all conversations” feature, but I couldn’t verify what I was deleting before committing.

The problem with manual filtering: you need to know the pattern beforehand. But spam and unwanted emails don’t follow consistent patterns.

The Solution

I discovered that Claude Code works with a Google Workspace CLI skill. This lets me use natural language to analyze and manage my Gmail.

Step 1: Install the GWS CLI Skill

First, I installed the Google Workspace CLI skill in Claude Code:

claude skill install gws

Then I authenticated with my Google account:

gws auth login

This opened a browser window for OAuth consent. After approving, I was connected.

Step 2: Validate the Connection

Before doing anything destructive, I ran validation queries:

How many emails are in my inbox? Also show me the labels I have.

Claude ran the commands and showed:

Total emails in inbox: 4,823
Labels: INBOX, SENT, DRAFTS, SPAM, TRASH, [Custom labels...]

I cross-checked this with Gmail’s web interface. The numbers matched. This gave me confidence the connection was working correctly.

Step 3: Identify Spam Patterns

Next, I asked Claude to analyze patterns in my inbox:

Look at the last 200 emails in my inbox. Identify patterns of spam or unwanted emails. What categories do you see?

Claude analyzed the emails and returned:

Found these patterns:

1. Newsletters (47 emails)
   - senders: newsletter@*, updates@*, noreply@*
   - subjects: "Weekly Update", "Monthly Digest", "Your subscription"

2. Promotional (89 emails)
   - senders: promotions@*, deals@*, offers@*
   - subjects: "% off", "Sale ends", "Limited time"

3. Notifications (32 emails)
   - senders: notifications@*, alerts@*
   - subjects: "New login", "Security alert", "Password changed"

4. Social media (28 emails)
   - senders: *@facebook.com, *@linkedin.com, *@twitter.com
   - subjects: "mentioned you", "liked your post"

This analysis would have taken me hours manually. Claude did it in seconds.

Step 4: Get a Sender Index

I wanted to see which senders were most frequent:

Create a sender index from my last 500 emails. Show me the top 20 senders by email count.

Claude returned a ranked list:

Top senders by email count:

1. [email protected] - 127 emails
2. [email protected] - 89 emails
3. [email protected] - 67 emails
4. [email protected] - 54 emails
5. [email protected] - 43 emails
...

I reviewed this list and marked which senders were safe to delete.

Step 5: Batch Processing

Gmail has API limits and Claude has context window limits. I learned to process emails in batches of about 100:

Find all emails from [email protected] in my inbox. Show me a sample of 5 emails so I can verify they're safe to delete. Then move all of them to Trash.

Claude showed me a sample first:

Sample emails from [email protected]:

1. "Weekly Update #127" - 2025-12-01
2. "Weekly Update #126" - 2025-11-24
3. "Weekly Update #125" - 2025-11-17
4. "Weekly Update #124" - 2025-11-10
5. "Weekly Update #123" - 2025-11-03

All appear to be newsletters. Proceed with moving 127 emails to Trash? [y/n]

I confirmed, and Claude moved the emails:

Moved 127 emails from [email protected] to Trash.

Emails in Trash are retained for 30 days before permanent deletion.
You can recover them from Trash if needed.

Step 6: Repeat for Other Categories

I repeated the process for other senders:

Process the next sender on my list: [email protected]. Same approach - show samples first, then move to Trash if I confirm.

I worked through the list systematically. Each batch showed samples before deletion, giving me a chance to catch mistakes.

Why Move to Trash Instead of Delete?

I learned this the hard way. In my first attempt, I used permanent deletion:

Delete all emails from spam-sender.com permanently.

Later, I realized one of those emails had an important receipt. I couldn’t recover it.

The correct approach:

Move all emails from spam-sender.com to Trash.

Trash retains emails for 30 days. This gives me a safety window to recover anything I accidentally deleted.

My Complete Workflow

Here’s the workflow that worked for me:

1. Validate connection - count emails, check labels
2. Analyze patterns - identify spam categories
3. Get sender index - rank by email count
4. Review samples - verify before any deletion
5. Batch process - ~100 emails at a time
6. Move to Trash - never permanent delete
7. Verify results - check inbox count decreased
8. Wait 30 days - then Trash auto-empties

Results

After following this workflow:

Before: 4,823 emails in inbox
After: 87 emails in inbox

Time spent: ~2 hours (mostly reviewing samples)
Emails moved to Trash: 4,736

I reduced my inbox from thousands to under 100 emails. The entire process took about 2 hours, but most of that was me reviewing samples before confirming deletions.

Common Mistakes to Avoid

I made several mistakes during my cleanup:

Mistake 1: Skipping validation

WRONG: Jump straight to deleting emails
CORRECT: First validate counts match Gmail web interface

Always verify the CLI connection works correctly before destructive operations.

Mistake 2: Processing too many emails at once

WRONG: "Delete all 4000+ emails from these senders"
CORRECT: "Process 100 emails from this sender, then continue"

Claude has context window limits. Large batches cause errors or incomplete operations.

Mistake 3: Permanent deletion

WRONG: Delete emails permanently
CORRECT: Move to Trash (30-day recovery window)

Permanent deletion cannot be undone. Always use Trash first.

Mistake 4: Not checking samples

WRONG: Trust the sender name completely
CORRECT: Always review sample emails before confirming

Some senders send both spam and important emails. Samples help catch this.

Privacy Considerations

Using Claude Code with Gmail means Claude reads your emails. Consider:

Email content: Claude sees email subjects, senders, and snippets during analysis
Authentication: You grant OAuth access to the GWS CLI skill
Data retention: Check Claude’s data retention policy for your account type

If you handle sensitive emails (financial, health, legal), review Anthropic’s privacy policy first.

Summary

I cleaned thousands of Gmail emails using Claude Code with the Google Workspace CLI skill. The key point is using natural language prompts to analyze patterns, verify samples, and batch-move emails to Trash instead of permanent deletion.

The workflow is:

Validate connection and counts
Analyze patterns with natural language
Get sender index for decision-making
Review samples before any action
Process in batches (~100 emails)
Move to Trash for 30-day recovery window

This approach combines AI intelligence with safety checks. You get the speed of bulk operations with the verification of manual review.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

👨‍💻 Reddit Discussion
👨‍💻 Claude Code
👨‍💻 Google Workspace CLI

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!