# Gws Gmail Watch

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

Source: https://skillsagentes.com/skills/googleworkspace/cli/gws-gmail-watch
Repository: https://github.com/googleworkspace/cli
Author: googleworkspace
License: Apache-2.0
Updated: hace 4 meses
Context cost: 14 tok installed, 486 tok once triggered, 486 tok with every bundled file
Bundle: 1 file, 2 KB
Permissions requested: none declared

## Install

```bash
npx -y skills add googleworkspace/cli --skill gws-gmail-watch --agent claude-code
```

## What it does

- Ejecuta `gws gmail +watch` para monitorizar Gmail y transmitir nuevos correos como NDJSON
- Configura recursos de Pub/Sub en GCP (proyecto, topic, suscripción) o reutiliza los existentes
- Filtra por etiquetas de Gmail, controla el tamaño de lote y el intervalo de sondeo
- Permite escribir cada mensaje en un archivo JSON separado con --output-dir
- Limpia los recursos de Pub/Sub creados al salir con --cleanup

## Use it when

- Necesitas recibir y procesar correos de Gmail nuevos en tiempo real como stream NDJSON
- Quieres integrar notificaciones push de Gmail vía Pub/Sub sin configurar todo manualmente

## What triggers it

- "Vigila mi bandeja de Gmail y muéstrame los correos nuevos en NDJSON"
- "Configura un watch de Gmail con mi proyecto de GCP y limpia los recursos al terminar"
- "Haz un pull único de los correos con la etiqueta INBOX"

## Before you install

- Requiere el binario `gws` y haber leído ../gws-shared/SKILL.md para autenticación, flags globales y reglas de seguridad.

## Files

- SKILL.md — 2 KB

## SKILL.md

Reproduced verbatim from googleworkspace/cli under Apache-2.0. This section is the upstream document and is in English.

# 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

```bash
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

```bash
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](../gws-shared/SKILL.md) — Global flags and auth
- [gws-gmail](../gws-gmail/SKILL.md) — All send, read, and manage email commands

---

Skills Agentes — https://skillsagentes.com/skills/googleworkspace/cli/gws-gmail-watch