gws-gmail-watch

Watch Gmail for new emails and stream them as NDJSON via Pub/Sub.

Updated Nov 9, 2023
One-click install
npx skills add https://github.com/oresttokovenko/dot-files --skill gws-gmail-watch-oresttokovenko
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: gws-gmail-watch
Source: https://github.com/oresttokovenko/dot-files/tree/main/chezmoi/dot_agents/skills/gws-gmail-watch
Command: npx skills add https://github.com/oresttokovenko/dot-files --skill gws-gmail-watch-oresttokovenko

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Manually polling a Gmail inbox for new messages is inefficient and error-prone. This Skill sets up Gmail push notifications through Google Cloud Pub/Sub and streams incoming emails as NDJSON, enabling real-time email-driven automation. ## Core Features & Use Cases - Real-Time Email Streaming: Watch a Gmail mailbox and receive new messages as NDJSON events via Pub/Sub push notifications. - Flexible Filtering and Output: Filter by Gmail label IDs, control message format (full, metadata, minimal, raw), and write each message to a separate JSON file with --output-dir. - Resource Lifecycle Management: Reuse existing Pub/Sub topics and subscriptions, or clean up created resources automatically on exit with --cleanup. - Use Case: Trigger a downstream pipeline whenever a new invoice arrives in your INBOX by running a one-shot watch with label filters and writing messages to a directory for processing. ## Quick Start Ask the assistant to watch your Gmail inbox for new messages in your GCP project and stream them as NDJSON, for example by running gws gmail +watch with your project ID.

Frequently Asked Questions about gws-gmail-watch

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

FAQPage Schema
How do I watch Gmail for new emails from the command line?▼

Run gws gmail +watch with your GCP project ID to set up Gmail push notifications via Pub/Sub and stream new messages as NDJSON. Use --label-ids to filter specific labels like INBOX or UNREAD.

How to filter Gmail watch notifications by label?▼

Pass the --label-ids flag with a comma-separated list of Gmail label IDs, such as INBOX,UNREAD. Only messages matching those labels will be pushed and streamed.

Does Gmail watch expire and need renewal?▼

Yes, Gmail watch registrations expire after 7 days. Re-run the gws gmail +watch command to renew the watch and continue receiving push notifications.

Can I reuse an existing Pub/Sub subscription for Gmail push?▼

Yes, pass --subscription with an existing subscription name to skip setup, or --topic for an existing topic that already has Gmail push permission granted.

How do I save streamed Gmail messages to files?▼

Use the --output-dir flag to write each incoming message to a separate JSON file in the specified directory. Combine with --msg-format to control whether files contain full, metadata, minimal, or raw message content.