skilld
All skills
googleworkspace avatar

/gws-gmail-watch

@705fb0e
by Google Workspacegoogleworkspace/cli31k stars
1,856

Gmail: Watch for new emails and stream them as NDJSON.

Ask your Agent

Use this Skill: https://skilld.dev/gh/googleworkspace/cli/gws-gmail-watch

This session only. Nothing lands on disk.

SKILL.md

≈18 tokens always: the name and description. ≈424 when used: this file.

gmail +watch

PREREQUISITE: Read ../gws-shared/SKILL.md for auth, global flags, and security rules. If missing, run gws generate-skills to 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

Source: SKILL.md on GitHub

Third-party checks

1 warning17d5 checks · Risk SAFE
  • Gen Agent Trust Hub17d

    This skill allows an agent to monitor and stream Gmail messages using the gws CLI. The primary security risk is that the agent will process untrusted content from incoming emails, which could contain malicious instructions designed to manipulate the agent's behavior.

  • Socket17d

    No alerts

  • Snyk17d

    Risk: MEDIUM · 1 issue

  • Runlayer7mo

    1/1 file flagged

  • ZeroLeaks5mo

    Score: 93/100 · 2 sections analyzed

Provenance

Signed by skilld at 705fb0e. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 2 months ago.

Activeupdated 6 months ago

Capability

Other metadata
metadata
{
  "version": "0.22.5",
  "openclaw": {
    "category": "productivity",
    "requires": {
      "bins": [
        "gws"
      ]
    },
    "cliHelp": "gws gmail +watch --help"
  }
}

Topics

  • CLI
  • gmail
  • google-workspace
  • pub-sub
  • email
  • streaming
  • ndjson
  • gcp
  • watch

README badge

README badge for googleworkspace/cli/gws-gmail-watch

What it does

Watches Gmail for new emails and streams them as NDJSON via Google Cloud Pub/Sub, with options to filter by label, batch size, and output format. Use this to build email intake pipelines or monitor specific Gmail labels in real time without polling the Gmail API directly.

Generated from the current SKILL.md.

Frequently asked

Does this work with Gmail accounts that have 2FA enabled?
Authentication is handled by the shared gws-shared skill, which manages Google Workspace OAuth. 2FA is handled by Google's auth flow—no special setup needed.
How long does the watch stay active?
Gmail watch expires after 7 days. You must re-run the command to renew the subscription.
What happens to Pub/Sub resources if I stop the command?
By default, Pub/Sub topic and subscription persist after exit, allowing you to reconnect without recreating them. Use --cleanup to delete them on exit.
Can I filter emails by labels?
Yes. Use the --label-ids flag with comma-separated Gmail label IDs like INBOX or UNREAD to watch only messages in those labels.

Generated from the current SKILL.md. These answers refresh after source changes.