Gws Gmail Read
Read a Gmail message by ID and pull plain text, HTML, or JSON headers through the `gws` CLI inside an agent workflow.
Overview
gws-gmail-read is an agent skill for the Grow phase that reads one Gmail message by ID and returns body text, HTML, or headers through the gws CLI.
Install
npx skills add https://github.com/googleworkspace/cli --skill gws-gmail-readWhat is this skill?
- Fetches one message by Gmail message ID via `gws gmail +read`
- Optional `--headers` for From, To, Subject, and Date
- `--format json` plus jq-friendly body extraction
- Auto-decodes multipart/alternative and HTML-only mail to plain text
- `--dry-run` previews the API request without sending it
- 6 documented CLI flags including required --id
Adoption & trust: 16.4k installs on skills.sh; 26.9k GitHub stars; 2/3 security scanners passed (skills.sh audits).
What problem does it solve?
Your agent has a Gmail message ID but no reliable way to pull the full body or headers without manual copy-paste from the inbox.
Who is it for?
Solo builders wiring Gmail into OpenClaw or gws-based agents for support triage and scripted inbox reads.
Skip if: Bulk mailbox sync, sending mail, or teams that cannot install the gws CLI and complete gws-shared OAuth setup.
When should I use this skill?
You need to read a Gmail message and extract its body or headers using gws with a known message ID.
What do I get? / Deliverables
You get decoded message content or JSON-ready fields you can pipe into summarization, CRM updates, or the next gws-gmail action.
- Plain text or HTML message body
- Optional header block or JSON payload for downstream tools
Recommended Skills
Journey fit
Customer and ops email triage sits in Grow support—agents need message bodies and metadata without opening the Gmail UI. Support workflows start from reading inbound mail; this command is the fetch step before drafting replies or tickets.
How it compares
Use this focused read command instead of generic REST snippets when you already standardize on the gws skill pack.
Common Questions / FAQ
Who is gws-gmail-read for?
Indie builders and agent operators who use Google Workspace CLI skills to automate reading specific Gmail threads during support or ops workflows.
When should I use gws-gmail-read?
Use it in Grow support when you have a message ID and need body or headers; also in Operate iterate loops when agents verify inbound mail after deploy or billing alerts.
Is gws-gmail-read safe to install?
It invokes the gws CLI against your Google account—review the Security Audits panel on this page and follow gws-shared auth and scope rules before granting access.
SKILL.md
READMESKILL.md - Gws Gmail Read
# gmail +read > **PREREQUISITE:** Read `../gws-shared/SKILL.md` for auth, global flags, and security rules. If missing, run `gws generate-skills` to create it. Read a message and extract its body or headers ## Usage ```bash gws gmail +read --id <ID> ``` ## Flags | Flag | Required | Default | Description | |------|----------|---------|-------------| | `--id` | ✓ | — | The Gmail message ID to read | | `--headers` | — | — | Include headers (From, To, Subject, Date) in the output | | `--format` | — | text | Output format (text, json) | | `--html` | — | — | Return HTML body instead of plain text | | `--dry-run` | — | — | Show the request that would be sent without executing it | ## Examples ```bash gws gmail +read --id 18f1a2b3c4d gws gmail +read --id 18f1a2b3c4d --headers gws gmail +read --id 18f1a2b3c4d --format json | jq '.body' ``` ## Tips - Converts HTML-only messages to plain text automatically. - Handles multipart/alternative and base64 decoding. ## 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