1---
2name: gws-gmail-watch
3description: "Gmail: Watch for new emails and stream them as NDJSON."
4metadata:
5  version: 0.22.5
6  openclaw:
7    category: "productivity"
8    requires:
9      bins:
10        - gws
11    cliHelp: "gws gmail +watch --help"
12---
13 
14# gmail +watch
15 
16> **PREREQUISITE:** Read `../gws-shared/SKILL.md` for auth, global flags, and security rules. If missing, run `gws generate-skills` to create it.
17 
18Watch for new emails and stream them as NDJSON
19 
20## Usage
21 
22```bash
23gws gmail +watch
24```
25 
26## Flags
27 
28| Flag | Required | Default | Description |
29|------|----------|---------|-------------|
30| `--project` | — | — | GCP project ID for Pub/Sub resources |
31| `--subscription` | — | — | Existing Pub/Sub subscription name (skip setup) |
32| `--topic` | — | — | Existing Pub/Sub topic with Gmail push permission already granted |
33| `--label-ids` | — | — | Comma-separated Gmail label IDs to filter (e.g., INBOX,UNREAD) |
34| `--max-messages` | — | 10 | Max messages per pull batch |
35| `--poll-interval` | — | 5 | Seconds between pulls |
36| `--msg-format` | — | full | Gmail message format: full, metadata, minimal, raw |
37| `--once` | — | — | Pull once and exit |
38| `--cleanup` | — | — | Delete created Pub/Sub resources on exit |
39| `--output-dir` | — | — | Write each message to a separate JSON file in this directory |
40 
41## Examples
42 
43```bash
44gws gmail +watch --project my-gcp-project
45gws gmail +watch --project my-project --label-ids INBOX --once
46gws gmail +watch --subscription projects/p/subscriptions/my-sub
47gws gmail +watch --project my-project --cleanup --output-dir ./emails
48```
49 
50## Tips
51 
52- Gmail watch expires after 7 days — re-run to renew.
53- Without --cleanup, Pub/Sub resources persist for reconnection.
54- Press Ctrl-C to stop gracefully.
55 
56## See Also
57 
58- [gws-shared](../gws-shared/SKILL.md) — Global flags and auth
59- [gws-gmail](../gws-gmail/SKILL.md) — All send, read, and manage email commands
60