gws-gmail-watch

Stream new Gmail messages as NDJSON via Google Cloud Pub/Sub.

Updated Apr 6, 2026
One-click install
npx skills add https://github.com/cellarwood/figurio --skill gws-gmail-watch-cellarwood
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: gws-gmail-watch
Source: https://github.com/cellarwood/figurio/tree/main/skills/gws-gmail-watch
Command: npx skills add https://github.com/cellarwood/figurio --skill gws-gmail-watch-cellarwood

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Monitoring Gmail mailboxes for new messages and reliably exporting them in a machine-friendly NDJSON stream can be time-consuming to implement and operate, especially when you need near-real-time ingestion into processing pipelines or archival systems. This Skill centralizes the watch flow, Pub/Sub integration, and message formatting so teams can focus on downstream processing instead of connection and resource management.

Core Features & Use Cases

  • Gmail watch integration: Uses Gmail watch semantics to detect new messages and renew watches as needed.
  • Pub/Sub orchestration: Creates or uses Google Cloud Pub/Sub topics and subscriptions to receive push or pull notifications.
  • Filtering and formatting: Supports label-based filtering, configurable message formats (full, metadata, minimal, raw), batch pull sizes, polling intervals, and streaming outputs as NDJSON or individual files for ETL workflows.
  • Operational controls: Options to run once, cleanup created Pub/Sub resources, and write messages to an output directory for offline processing.
  • Use Case: Stream incoming support emails into an analytics pipeline or archival store that requires NDJSON lines for each message.

Quick Start

Run gws gmail +watch with your GCP project ID to stream incoming messages as NDJSON to stdout.

Frequently Asked Questions about gws-gmail-watch

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I stream new Gmail messages as NDJSON for an analytics pipeline?

You can stream Gmail messages as NDJSON by running the watch command with a GCP project ID. It uses Gmail watch semantics and Google Cloud Pub/Sub topics to output newline-delimited JSON lines to stdout for downstream processing.

Do I need a Google Workspace account to use Gmail watch for email ingestion?

Yes, near-real-time email ingestion via Gmail watch targets GWS-enabled Google Workspace accounts. It integrates with Google Cloud Pub/Sub to receive push or pull notifications and stream new messages as NDJSON.

Can I filter Gmail messages by label when streaming to Pub/Sub?

Yes, label-based filtering is supported when streaming Gmail messages through Pub/Sub. You can also configure message formats (full, metadata, minimal, raw), batch pull sizes, and polling intervals to control the NDJSON output.

What is the best way to automate near-real-time email ingestion from Gmail?

The best way to automate near-real-time email ingestion is using Gmail watch with Google Cloud Pub/Sub topics and subscriptions. This Skill orchestrates the watch flow, handles watch renewals, and streams new messages as NDJSON for processing pipelines.

Does Gmail watch clean up created Google Cloud Pub/Sub resources automatically?

Yes, operational controls include an option to clean up created Pub/Sub resources automatically. You can also configure the Skill to run once, write messages to an output directory for offline processing, or stream NDJSON directly to stdout.

What Gmail message formats are supported when exporting to NDJSON?

Supported Gmail message formats include full, metadata, minimal, and raw. These configurable formats let you control the level of detail in each NDJSON line streamed through Pub/Sub, optimizing for batch pull sizes and downstream ETL workflow requirements.