AutoGineer
Generated banner for Gws Gmail Watch
Generated logo for Gws Gmail Watch

Gws Gmail Watch

Google WorkspaceOfficialPublished by Google Workspace

  • Skill
  • Tool integration
  • Automation and integrations
  • Apache-2.0
  • No issues found
Download ZIP

From the author

Gmail: Watch for new emails and stream them as NDJSON.
— the description by Google Workspace

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

The gws-gmail-watch skill provides a command-line interface to monitor Gmail for new messages and stream them in NDJSON format. It leverages Google Cloud Pub/Sub infrastructure to track email activity, allowing users to filter by label, configure polling intervals, and optionally persist messages to local files.

What it does

  • Monitors Gmail accounts for incoming messages based on specified labels.
  • Streams retrieved email data in NDJSON format.
  • Supports integration with Google Cloud Pub/Sub for message delivery.
  • Allows filtering of emails using Gmail label IDs.
  • Provides options to save individual messages as separate JSON files.
  • Supports configurable polling intervals and batch sizes.

When to use it

  • When you need to ingest Gmail data into a data pipeline or local file system.
  • When you want to automate the processing of incoming emails based on specific labels.
  • When you need to integrate Gmail activity with Google Cloud Pub/Sub infrastructure.
  • When you require a programmatic way to extract email content in a structured format.

Advantages

  • Enables structured data output for downstream processing.
  • Provides flexible configuration for Pub/Sub topics and subscriptions.
  • Supports automated cleanup of cloud resources after execution.
  • Allows for both continuous monitoring and one-time batch retrieval.

Usage examples

“gws gmail +watch --project my-gcp-project”
Starts monitoring for new emails in the specified GCP project and streams them as NDJSON.
“gws gmail +watch --project my-project --label-ids INBOX --once”
Performs a single pull of unread inbox messages and exits.
“gws gmail +watch --project my-project --cleanup --output-dir ./emails”
Monitors for emails, saves each as a separate JSON file in the specified directory, and cleans up Pub/Sub resources upon exit.

Install

  1. Download the skill as a ZIP:

    https://autogineer.com/agent-skills/googleworkspace/gws-gmail-watch/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip gws-gmail-watch.zip -d .agents/skills

Documentation by Google Workspace

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

FlagRequiredDefaultDescription
--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—10Max messages per pull batch
--poll-interval—5Seconds between pulls
--msg-format—fullGmail 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.

See Also

  • gws-shared — Global flags and auth

  • gws-gmail — All send, read, and manage email commands

Files

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Published by
Google Workspace
Publisher
Google Workspace (Official)
Source
googleworkspace/cli · skills/gws-gmail-watch · commit cd3697e
Licence
Apache License 2.0 (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by Google Workspace or Google Workspace.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download gws-gmail-watch.zip