AgentSkillsCN

gmailtail

通过命令行搜索、归档、标记并分析Gmail。当用户想要搜索邮件、清理收件箱、归档消息、创建过滤器、取消订阅列表、下载附件，或分析收件箱模式时使用此功能。

SKILL.md
--- frontmatter
name: gmailtail
description: Search, archive, label, and analyze Gmail from the command line. Use when user wants to search emails, clean up inbox, archive messages, create filters, unsubscribe from lists, download attachments, or analyze inbox patterns.

gmailtail - Gmail CLI Tool

A command-line tool for monitoring and managing Gmail with support for batch operations, filtering, and inbox analysis.

Installation

bash
# Install with uv (recommended)
uv tool install gmailtail

# Or with pip
pip install gmailtail

# First run will open browser for OAuth authentication
gmailtail --once

Quick Reference

Search & Read

bash
# Search emails
gmailtail --query "from:example@gmail.com" --once

# View full email content (human-readable)
gmailtail --query "subject:invoice" --show --max-messages 5

# Get JSON output for processing
gmailtail --query "in:inbox" --format json-lines --once --max-messages 100

Archive & Cleanup

CRITICAL: Always include in:inbox when archiving to avoid infinite loops:

bash
# CORRECT - only processes emails in inbox
gmailtail --query "from:notifications@github.com in:inbox" --archive --max-messages 100

# WRONG - finds already-archived emails, loops forever
gmailtail --query "from:notifications@github.com" --archive --loop

For mark-as-read, include is:unread:

bash
gmailtail --query "from:example@gmail.com is:unread" --mark-read --max-messages 100

Batch Operations

bash
# Archive with loop (processes >1000 messages)
gmailtail --query "from:spam@ in:inbox" --archive --loop

# Add labels
gmailtail --query "from:finance@bank.com in:inbox" --add-label "Finance"

# Trash messages
gmailtail --query "from:spam@ in:inbox" --trash --max-messages 50

# Star messages
gmailtail --query "subject:important in:inbox" --star --max-messages 20

# Unsubscribe from mailing lists
gmailtail --query "from:newsletter@ in:inbox" --unsubscribe --max-messages 10

Download Attachments

bash
# Download to directory
gmailtail --query "from:invoices@vendor.com" --download-attachments ./invoices

# With date range
gmailtail --query "has:attachment after:2025/01/01" --download-attachments ./downloads --max-messages 50

Filter Management

bash
# Create auto-archive filter with label
gmailtail --create-filter "marketing@company.com" --filter-label "Marketing" --filter-archive

# Create label-only filter (stays in inbox)
gmailtail --create-filter "important@company.com" --filter-label "Important"

# Delete a filter
gmailtail --delete-filter "filter_id_here"

Monitoring Modes

bash
# Real-time tail (like tail -f)
gmailtail --tail

# Interactive REPL
gmailtail --repl

Inbox Analysis Workflow

For detailed inbox analysis and cleanup workflows, see ANALYSIS.md. For filter management best practices, see FILTERS.md. For step-by-step cleanup sessions, see CLEANUP.md.

Output Formats

  • •--format compact - One line per email (default)
  • •--format json - Full JSON array
  • •--format json-lines - One JSON object per line (best for processing)
  • •--show - Human-readable with full body

Important Notes

  1. •Cache API responses when doing multiple analyses - Gmail API is slow
  2. •Always use in:inbox for archive operations
  3. •Check transactional vs marketing before creating auto-archive filters
  4. •Prefer unsubscribe over filtering for senders with mixed content