# Monitor Gmail Messages with Pub/Sub

New Gmail messages are difficult to monitor continuously through manual checks. This skill streams incoming messages as NDJSON through Google Cloud Pub/Sub.

## Install

```bash
npx skillstore add googleworkspace/gws-gmail-watch
```

## Metadata

- Status: approved
- Slug: googleworkspace-gws-gmail-watch
- Version: 0.23.0
- Author version: 0.23.0
- Skillstore revision: r2
- Version status: valid
- Tree hash: 56abfecc3dbaae9db68a8c1c690e8de4b1534de6f1be30e6f088aeea11f64ec6
- Author: googleworkspace
- GitHub username: googleworkspace
- License: MIT
- Repository: https://github.com/googleworkspace/cli/tree/main/skills/gws-gmail-watch/
- Ref: 286d37c9c189ddd1aafd3548415fb031d1df79d5
- Supported tools: Claude, Codex, Claude Code
- Audit status: complete
- Agent install advisory: allowed
- Manual install advisory: allowed
- Artifact signature: available
- Audit attestation: unavailable
- Human verification: not\_verified
- Risk factors: external\_commands, filesystem
- Quality score: 80
- Quality tier: silver
- Public page: https://skillstore.pages.dev/skills/googleworkspace-gws-gmail-watch
- Manifest: https://skillstore.pages.dev/api/skills/googleworkspace-gws-gmail-watch/manifest

## Capabilities

- Starts a Gmail watch process and streams new messages as NDJSON.
- Connects through a specified Google Cloud project or an existing Pub/Sub subscription.
- Filters watched messages by one or more Gmail label IDs.
- Controls pull batch size, polling interval, and Gmail message format.
- Supports a single-pull mode for scheduled or test workflows.
- Can write each message to a separate file and clean up created Pub/Sub resources.

## Use Cases

- Monitor an Operations Inbox: Stream new inbox messages into an event-processing workflow with controlled polling and batch sizes.
- Test Gmail Automations: Pull one batch of labeled messages to verify an integration without running a continuous watcher.
- Archive Incoming Messages: Write each watched message to a separate file for approved review or retention workflows.

## Prompt Templates

### Watch New Gmail Messages

```
Watch for new Gmail messages using my authenticated gws setup and stream the results as NDJSON.
```

### Watch a Specific Label

```
Watch Gmail messages with the INBOX label in project [PROJECT_ID]. Pull one batch, then stop.
```

### Use an Existing Subscription

```
Watch Gmail through Pub/Sub subscription [SUBSCRIPTION_NAME]. Use metadata format, pull up to [COUNT] messages, and poll every [SECONDS] seconds.
```

### Persist and Clean Up

```
Watch labeled Gmail messages in project [PROJECT_ID]. Write each message to [OUTPUT_DIRECTORY], then remove resources created by this session on exit.
```

## Limitations

- Requires the gws CLI, Google authentication, and suitable Gmail and Pub/Sub permissions.
- Gmail watches expire after seven days and must be renewed.
- The skill streams message data but does not interpret, summarize, or reply to email.
- Pub/Sub resources remain after exit unless cleanup is explicitly enabled.

## Best Practices

- Use the narrowest Gmail labels and message format required for the workflow.
- Protect output files because full Gmail messages can contain sensitive information.
- Use an existing Pub/Sub subscription when resource lifecycle is managed elsewhere.

## Anti Patterns

- Do not enable cleanup when other workflows depend on the created Pub/Sub resources.
- Do not store full messages in a broadly accessible directory.
- Do not assume the watch remains active beyond seven days.

## Security Audit

- Audited at: 2026-08-05T11:14:00.054\+00:00
- Summary: All 17 static findings are false positives caused by Markdown code formatting and fixed sibling documentation links. The reviewed skill contains no shell backtick execution, path traversal behavior, prompt injection, or malicious intent.

## Stats

- Views: 85
- Downloads: 7
- Favorites: 0
- Popularity score: 0