Skip to content
Get packs

Gmail New-Mail Watcher

Lets an agent watch a Gmail inbox and stream new emails as NDJSON via the gws CLI.

Source Download skill
Repository
googleworkspace/cli
Stars
32,059
Licence
Apache-2.0
Files
1 file

What it does

This skill teaches an AI agent how to use the gws command-line tool to watch a Gmail account for new messages and print each one as a line of JSON (NDJSON). It can filter by Gmail labels, save each message to its own file, and set up or reuse Google Cloud Pub/Sub resources that Gmail uses to push notifications. It is a how-to for one command rather than a standalone app.

Great for

  • Developers who want an agent to react to incoming Gmail messages in a pipeline
  • People automating inbox triage who already use the gws CLI and have Google Cloud set up
  • Anyone who needs a stream of new emails saved as JSON files for later processing

Skip it if

  • Users without a Google Cloud project or Gmail access, since setup needs GCP Pub/Sub permissions
  • Sensitive mailboxes where streaming full message content to logs or files could expose private data
  • Sending or managing email: the skill only covers watching for new messages (see gws-gmail for other commands)

Try asking

  • “Watch my inbox for new unread emails and stream them as JSON using project my-gcp-project”
  • “Pull once the newest INBOX messages and save each one as a file in ./emails”
  • “Reconnect to my existing Pub/Sub subscription and print new Gmail messages”
  • “Stop the Gmail watch and delete the Pub/Sub resources I created with --cleanup”
Step-by-step guide: how to use Gmail New-Mail WatcherInstall, first run, examples, tips and FAQs

Install in 3 steps

  1. 1

    Download the skill

    The ZIP contains the 1 original files, the Apache-2.0 licence and an attribution note.

    gws-gmail-watch.zip
  2. 2

    Add it to your agent

    Claude Code (all projects)

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

    Claude Code / Agent SDK (this project only)

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

    Claude apps (web/desktop): Settings → Capabilities → Skills → Upload skill, and choose the ZIP.

  3. 3

    Ask for the task

    No special command needed — the agent reads the skill's description and loads it when your request matches. Try one of the prompts above.

Get better results

  • Run with --once first to confirm the output format and filters before streaming continuously.
  • Remember Gmail watches expire after 7 days, so re-run the command to renew them.
  • Use --cleanup when finished so created Pub/Sub resources are removed, and avoid committing output directories containing private email.

What's inside

  • SKILL.md

Redistributed unmodified from googleworkspace/cli under the Apache-2.0 licence. The assessment was drafted with AI from the skill's files on 2026-10-29. Skills can instruct your agent to run code — read SKILL.md and any scripts before installing.