Gws Gmail Watch
Stream new Gmail messages as NDJSON (or per-file JSON) for inbox-driven agents using gws gmail +watch and optional Pub/Sub setup.
Overview
Gws Gmail Watch is an agent skill for the Build phase that watches Gmail for new messages and streams them as NDJSON using the gws gmail +watch CLI with Pub/Sub and label filters.
Install
npx skills add https://github.com/googleworkspace/cli --skill gws-gmail-watchWhat is this skill?
- Streams new emails as NDJSON via gws gmail +watch
- Modes: continuous poll (default interval 5s), --once single pull, or --output-dir per-message JSON files
- GCP options: --project, --topic, --subscription, optional --cleanup on exit
- msg-format variants: full, metadata, minimal, raw
- Label filter via --label-ids (e.g., INBOX,UNREAD); --max-messages default 10 per batch
- Default --max-messages 10 per pull batch
- Default --poll-interval 5 seconds
- 4 msg-format options: full, metadata, minimal, raw
Adoption & trust: 20.3k installs on skills.sh; 26.9k GitHub stars; 2/3 security scanners passed (skills.sh audits).
What problem does it solve?
You need reliable, scriptable new-mail events for an agent pipeline instead of polling Gmail in bespoke code or missing pushes.
Who is it for?
Indie builders integrating Gmail-triggered automations who already use gws and can manage GCP Pub/Sub for push watch.
Skip if: Bulk historical mailbox migration, sending mail, or teams unwilling to configure GCP project, topic, and subscription permissions.
When should I use this skill?
Gmail: Watch for new emails and stream them as NDJSON.
What do I get? / Deliverables
A running watch (or a single --once batch) emits structured message records your agent can parse, with optional per-file JSON under --output-dir.
- NDJSON stream of new Gmail messages
- Optional per-message JSON files in --output-dir
Recommended Skills
Journey fit
Canonical shelf is Build because the skill wires Gmail push/pull watching into your product or agent stack—not a marketing or ops playbook by itself. Integrations is the right facet for Gmail Pub/Sub topics, subscriptions, label filters, and NDJSON streaming into downstream automation.
How it compares
This is a gws CLI integration skill—not an MCP server—and it complements manual IMAP scripts with documented Pub/Sub and NDJSON streaming flags.
Common Questions / FAQ
Who is gws-gmail-watch for?
Solo builders and small teams wiring Claude Code, Cursor, or Codex agents to Gmail via the gws CLI and Google Cloud Pub/Sub.
When should I use gws-gmail-watch?
Use it during Build integrations when standing up inbox automations; in Operate monitoring when you want label-filtered unread streams; avoid it until gws-shared auth rules are loaded.
Is gws-gmail-watch safe to install?
It touches live mail and cloud Pub/Sub resources—review the Security Audits panel on this page, gws-shared security rules, and least-privilege GCP and Gmail scopes.
SKILL.md
READMESKILL.md - Gws Gmail Watch
# gmail +watch > **PREREQUISITE:** Read `../gws-shared/SKILL.md` for auth, global flags, and security rules. If missing, run `gws generate-skills` to create it. Watch for new emails and stream them as NDJSON ## Usage ```bash gws gmail +watch ``` ## Flags | Flag | Required | Default | Description | |------|----------|---------|-------------| | `--project` | — | — | GCP project ID for Pub/Sub resources | | `--subscription` | — | — | Existing Pub/Sub subscription name (skip setup) | | `--topic` | — | — | Existing Pub/Sub topic with Gmail push permission already granted | | `--label-ids` | — | — | Comma-separated Gmail label IDs to filter (e.g., INBOX,UNREAD) | | `--max-messages` | — | 10 | Max messages per pull batch | | `--poll-interval` | — | 5 | Seconds between pulls | | `--msg-format` | — | full | Gmail message format: full, metadata, minimal, raw | | `--once` | — | — | Pull once and exit | | `--cleanup` | — | — | Delete created Pub/Sub resources on exit | | `--output-dir` | — | — | Write each message to a separate JSON file in this directory | ## Examples ```bash gws gmail +watch --project my-gcp-project gws gmail +watch --project my-project --label-ids INBOX --once gws gmail +watch --subscription projects/p/subscriptions/my-sub gws gmail +watch --project my-project --cleanup --output-dir ./emails ``` ## Tips - Gmail watch expires after 7 days — re-run to renew. - Without --cleanup, Pub/Sub resources persist for reconnection. - Press Ctrl-C to stop gracefully. ## See Also - [gws-shared](../gws-shared/SKILL.md) — Global flags and auth - [gws-gmail](../gws-gmail/SKILL.md) — All send, read, and manage email commands