gws-gmail-watch

Gmail: Watch for new emails and stream them as NDJSON.

Quality

56%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Advisory

Suggest reviewing before use

Fix and improve this skill with Tessl

tessl review fix ./skills/gws-gmail-watch/SKILL.md

The canonical home for this skill is pleaseai/google-workspace

gmail +watch

Name: gws-gmail-watch
Rating: 51.2 (1 reviews)
Author: googleworkspace

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

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.