1---
2name: gmail-safe-batch-ops
3description: Search, preview, and batch-archive Gmail safely with gog auth, dry-run-first filters, and safety caps for inbox cleanup.
4allowed-tools: Bash Read
5---
6 
7# gmail-safe-batch-ops
8 
9Use this when you need Gmail search, inbox triage, or cautious batch cleanup without jumping straight into destructive mailbox changes.
10 
11## What this bundle gives you
12 
13- fast read-only Gmail search via `gog`
14- a bundled Python helper for preview-first mailbox filtering
15- guarded batch archive mode with message-count and ratio safety caps
16- JSON summaries that are easy to inspect, save, or review before applying changes
17 
18## Requirements
19 
20- `gog` installed and authenticated for Gmail
21- `python3` available
22- Gmail OAuth credentials already set up through `gog`
23- in headless environments, `GOG_KEYRING_PASSWORD` must be available or stored at the default `gog` keyring password path
24 
25## Read-only first
26 
27Use plain `gog` when you only need quick search results.
28 
29```bash
30gog gmail search 'newer_than:7d' --max 10
31gog gmail messages search 'in:inbox from:[email protected]' --max 20
32```
33 
34Use the bundled helper when you need stricter local filters, previews, exportable JSON, or guarded archive actions.
35 
36## Bundled helper
37 
38Run from this skill directory:
39 
40```bash
41python3 scripts/gmail_mail_tool.py --help
42```
43 
44### Common preview flows
45 
46Preview GitHub notifications older than 14 days:
47 
48```bash
49python3 scripts/gmail_mail_tool.py \
50  --account [email protected] \
51  --from-email [email protected] \
52  --older-than-days 14
53```
54 
55Preview newsletters by subject text and keep only inbox mail missing a label:
56 
57```bash
58python3 scripts/gmail_mail_tool.py \
59  --account [email protected] \
60  --subject-contains newsletter \
61  --missing-label IMPORTANT
62```
63 
64Preview with a Gmail query plus local sender filtering, then save JSON:
65 
66```bash
67python3 scripts/gmail_mail_tool.py \
68  --account [email protected] \
69  --query 'category:promotions newer_than:30d' \
70  --from-contains digest \
71  --out ./preview.json
72```
73 
74### Apply archive after preview
75 
76Only archive after checking the preview summary first.
77 
78```bash
79python3 scripts/gmail_mail_tool.py \
80  --account [email protected] \
81  --from-email [email protected] \
82  --older-than-days 30 \
83  --max-apply-messages 100 \
84  --apply
85```
86 
87Archive from all mail only when you truly mean it:
88 
89```bash
90python3 scripts/gmail_mail_tool.py \
91  --account [email protected] \
92  --all-mail \
93  --query 'label:newsletters older_than:90d' \
94  --has-label INBOX \
95  --apply
96```
97 
98## Safety rules
99 
100- default mode is preview only
101- `--apply` removes the `INBOX` label from selected messages; it does not delete mail
102- the helper refuses empty-filter runs unless you explicitly pass `--allow-empty-filter`
103- the helper refuses oversized apply runs unless you raise the caps or pass `--force-unsafe-apply`
104- for risky cleanups, save the preview JSON before applying changes
105 
106## Useful flags
107 
108- `--query` for Gmail-native filtering
109- `--from-email`, `--from-contains`, `--subject-contains`, `--snippet-contains` for local filtering
110- `--has-label` and `--missing-label` for label-aware cleanup
111- `--older-than-days` / `--newer-than-days` for age windows
112- `--sample-limit` to control preview size
113- `--out` to persist the JSON summary
114 
115## Environment overrides
116 
117The helper supports these optional environment variables:
118 
119- `GMAIL_TOOL_ACCOUNT`
120- `GOG_ACCOUNT`
121- `GMAIL_TOOL_GOG_CREDENTIALS`
122- `GMAIL_TOOL_GOG_KEYRING_PASSWORD_FILE`
123- `GMAIL_TOOL_LOG_FILE`
124- `GOG_KEYRING_PASSWORD`
125 
126## Recommended agent behavior
127 
1281. Start with read-only search or preview.
1292. Inspect sender, subject, date, labels, and sample output.
1303. Apply only after the preview matches the intended cleanup scope.
1314. For large mailboxes, narrow the query first instead of forcing a huge apply.
132