gws-gmail-watch
Helps your agent monitor and receive new Gmail emails. Allows the agent to process email information in real-time.
What it does
This command watches your Gmail inbox for new emails. When a new email arrives, it sends it to you as formatted text (NDJSON).
When to use it
- ✓When you want to be notified about important emails as soon as they arrive.
- ✓When automating tasks that depend on new emails (like processing orders).
- ✓To monitor specific emails based on their labels.
Example of what to ask your AI
“Watch for new emails in my inbox and let me know when one arrives.”
Want more? Open the sections below.
How to use
The easiest way: copy the message below and paste it into Claude, ChatGPT, Cursor or any AI. It reads the skill and follows the instructions.
Skill link
Ready-to-paste message
How it works
It uses a Google Cloud service to get notifications for new Gmail messages. These notifications are then sent to you in a text format that other programs can easily read.
Installation
Easiest way: copy the skill link and paste it into Claude, ChatGPT or Cursor asking it to follow the instructions.
In the terminal (Claude Code, Codex, Cursor), in your project folder:
npx skills add googleworkspace/cli --skill gws-gmail-watchOr download just the file:
curl -L https://raw.githubusercontent.com/googleworkspace/cli/main/skills/gws-gmail-watch/SKILL.md -o SKILL.mdTechnical content (original SKILL.md)
Original text by the author, straight from GitHub.
gmail +watch
PREREQUISITE: Read
../gws-shared/SKILL.mdfor auth, global flags, and security rules. If missing, rungws generate-skillsto 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.
See Also
- gws-shared — Global flags and auth
- gws-gmail — All send, read, and manage email commands
FAQ
How do I stop watching for emails?
You can stop the command by pressing Ctrl+C on your keyboard.
What happens to the emails that arrive?
They are sent as formatted text (NDJSON) to you. You can set it up to save them to files if you wish.
Do I need to set up anything in Google Cloud?
Yes, you might need to set up a Google Cloud project for the service to work. The command tries to set this up for you, but may ask for additional information.
Details
Original description by the author
Gmail: Watch for new emails and stream them as NDJSON.
repo: googleworkspace/cli
Popularity
- GitHub stars
- 32k
- Ranking position
- #6271
- License
- Apache-2.0
- Updated
- 10/6/2026
Comments
- …
More skills from this repository
gws-admin-reports
Helps your agent get activity reports from Google Workspace. It collects audit and usage data.
googleworkspace/cli
gws-calendar-agenda
Helps your agent see upcoming events across all calendars. It's useful for organizing your schedule and knowing what's coming up.
googleworkspace/cli
gws-calendar-insert
Lets your agent create new events in Google Calendar. It's useful for scheduling appointments and meetings.
googleworkspace/cli
gws-calendar
Allows your agent to manage calendars and events. It's useful for organizing your life and work.
googleworkspace/cli
Similar skills
google-workspace-ops
Operates with Google Workspace documents (Drive, Docs, Sheets, Slides) as a unified workflow. It makes it easy to find, summarize, and edit your files without leaving the tool.
affaan-m/ECC
Dynamics 365 Automation
Helps your agent manage customer information in Dynamics 365. It can handle contacts, sales, and cases, making work more organized.
ComposioHQ/awesome-claude-skills
Excel Automation
Helps your agent work with spreadsheets in Excel and Google Sheets. It can create, edit, and format files.
ComposioHQ/awesome-claude-skills