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.