gws-gmail-watch

googleworkspace/cli

Watch Gmail for new emails and stream them as NDJSON in real-time.

What is gws-gmail-watch?

Monitors a Gmail account for incoming emails and outputs them as newline-delimited JSON. Use this to integrate Gmail into automated workflows, trigger actions on new messages, or build custom email processing pipelines.

Stream new emails as NDJSON for real-time processing
Filter emails by Gmail label IDs (INBOX, UNREAD, etc.)
Configure message format (full, metadata, minimal, raw)
Pull emails in batches with configurable intervals
Write each message to separate JSON files
Gracefully handle watch expiration and reconnection

How to install gws-gmail-watch

npx skills add null --skill gws-gmail-watch

Prerequisites

Google Workspace account with Gmail enabled
GCP project with Pub/Sub API enabled
gws CLI installed and authenticated (see gws-shared skill)
Appropriate Gmail API permissions granted

Claude Code

Cursor

Windsurf

Cline

How to use gws-gmail-watch

1.Run `gws gmail +watch --project YOUR_GCP_PROJECT` to start watching for new emails
2.Optionally add `--label-ids INBOX,UNREAD` to filter specific labels
3.Use `--once` flag to pull messages once and exit, or omit to stream continuously
4.Add `--output-dir ./emails` to write each message to a separate JSON file
5.Press Ctrl-C to stop gracefully; use `--cleanup` to delete Pub/Sub resources on exit

Use cases

Good for

Trigger automated workflows when new emails arrive in specific labels
Export incoming emails to a data pipeline or logging system
Monitor unread emails and stream them to a notification system
Archive email metadata to a file-based system for analysis
Integrate Gmail with custom chatbots or AI agents that need email context

Who it's for

Automation engineers building email-triggered workflows
Developers integrating Gmail with custom applications
DevOps teams monitoring email-based alerts
Data engineers processing email streams

gws-gmail-watch FAQ

How long does Gmail watch stay active?

Gmail watch expires after 7 days. Re-run the command to renew the watch.

What happens to Pub/Sub resources when I stop watching?

By default, Pub/Sub resources persist for reconnection. Use `--cleanup` flag to delete them on exit.

Can I filter emails by label?

Yes, use `--label-ids` with comma-separated Gmail label IDs like `INBOX,UNREAD` to filter specific labels.

What message formats are available?

Four formats: `full` (default, complete message), `metadata` (headers only), `minimal` (basic info), and `raw` (RFC 2822 format).

Can I save emails to files instead of streaming?

Yes, use `--output-dir ./path` to write each message to a separate JSON file in that directory.

Full instructions (SKILL.md)

Source of truth, from googleworkspace/cli.

name: gws-gmail-watch description: "Gmail: Watch for new emails and stream them as NDJSON." metadata: version: 0.22.5 openclaw: category: "productivity" requires: bins: - gws cliHelp: "gws gmail +watch --help"

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

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

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