gmail-safe-batch-ops

Use this when you need Gmail search, inbox triage, or cautious batch cleanup without jumping straight into destructive mailbox changes.

What this bundle gives you

• fast read-only Gmail search via gog
• a bundled Python helper for preview-first mailbox filtering
• guarded batch archive mode with message-count and ratio safety caps
• JSON summaries that are easy to inspect, save, or review before applying changes

Requirements

• gog installed and authenticated for Gmail
• python3 available
• Gmail OAuth credentials already set up through gog
• in headless environments, GOG_KEYRING_PASSWORD must be available or stored at the default gog keyring password path

Read-only first

Use plain gog when you only need quick search results.

gog gmail search 'newer_than:7d' --max 10
gog gmail messages search 'in:inbox from:[email protected]' --max 20

Use the bundled helper when you need stricter local filters, previews, exportable JSON, or guarded archive actions.

Bundled helper

Run from this skill directory:

python3 scripts/gmail_mail_tool.py --help

Common preview flows

Preview GitHub notifications older than 14 days:

python3 scripts/gmail_mail_tool.py \
  --account [email protected] \
  --from-email [email protected] \
  --older-than-days 14

Preview newsletters by subject text and keep only inbox mail missing a label:

python3 scripts/gmail_mail_tool.py \
  --account [email protected] \
  --subject-contains newsletter \
  --missing-label IMPORTANT

Preview with a Gmail query plus local sender filtering, then save JSON:

python3 scripts/gmail_mail_tool.py \
  --account [email protected] \
  --query 'category:promotions newer_than:30d' \
  --from-contains digest \
  --out ./preview.json

Apply archive after preview

Only archive after checking the preview summary first.

python3 scripts/gmail_mail_tool.py \
  --account [email protected] \
  --from-email [email protected] \
  --older-than-days 30 \
  --max-apply-messages 100 \
  --apply

Archive from all mail only when you truly mean it:

python3 scripts/gmail_mail_tool.py \
  --account [email protected] \
  --all-mail \
  --query 'label:newsletters older_than:90d' \
  --has-label INBOX \
  --apply

Safety rules

• default mode is preview only
• --apply removes the INBOX label from selected messages; it does not delete mail
• the helper refuses empty-filter runs unless you explicitly pass --allow-empty-filter
• the helper refuses oversized apply runs unless you raise the caps or pass --force-unsafe-apply
• for risky cleanups, save the preview JSON before applying changes

Useful flags

• --query for Gmail-native filtering
• --from-email, --from-contains, --subject-contains, --snippet-contains for local filtering
• --has-label and --missing-label for label-aware cleanup
• --older-than-days / --newer-than-days for age windows
• --sample-limit to control preview size
• --out to persist the JSON summary

Environment overrides

The helper supports these optional environment variables:

• GMAIL_TOOL_ACCOUNT
• GOG_ACCOUNT
• GMAIL_TOOL_GOG_CREDENTIALS
• GMAIL_TOOL_GOG_KEYRING_PASSWORD_FILE
• GMAIL_TOOL_LOG_FILE
• GOG_KEYRING_PASSWORD

Recommended agent behavior

1. Start with read-only search or preview.
2. Inspect sender, subject, date, labels, and sample output.
3. Apply only after the preview matches the intended cleanup scope.
4. For large mailboxes, narrow the query first instead of forcing a huge apply.