Gws Gmail Read
- 33.1k installs
- 30k repo stars
- Updated July 22, 2026
- googleworkspace/cli
gws-gmail-read is a Google Workspace CLI skill that reads a Gmail message by ID and extracts its body or headers from the terminal.
About
gws-gmail-read is an agent skill wrapping the Google Workspace CLI command gws gmail +read. It reads a single Gmail message by ID and extracts the body or headers, with flags for headers, JSON output, HTML body, and dry-run. It converts HTML-only messages to plain text and handles multipart and base64 decoding. A developer or agent uses it to pull a specific email's content from the terminal or inside a larger gws workflow.
- Reads a Gmail message body or headers by ID from the CLI
- Text/JSON/HTML output with dry-run support
- Auto-converts HTML and handles base64/multipart decoding
Gws Gmail Read by the numbers
- 33,117 all-time installs (skills.sh)
- +1,388 installs in the week ending Jul 28, 2026 (Skillselion tracking)
- Ranked #43 of 3,301 Productivity & Planning skills by installs in the Skillselion catalog
- Security screen: MEDIUM risk (skills.sh audit)
- Data as of Jul 28, 2026 (Skillselion catalog sync)
gws-gmail-read capabilities & compatibility
Free skill; requires the gws CLI authenticated to a Google account
- Capabilities
- email read · header extraction · email parsing
- Works with
- gmail
- Use cases
- Pricing
- Free
What gws-gmail-read says it does
Gmail: Read a message and extract its body or headers.
Converts HTML-only messages to plain text automatically.
Handles multipart/alternative and base64 decoding.
npx skills add https://github.com/googleworkspace/cli --skill gws-gmail-readAdd your badge
Show developers this skill is listed on Skillselion. Paste this into your README.
| Installs | 33.1k |
|---|---|
| repo stars | ★ 30k |
| Security audit | 2 / 3 scanners passed |
| Last updated | July 22, 2026 |
| Repository | googleworkspace/cli ↗ |
How do I read a specific Gmail message's body or headers from the terminal or an agent workflow?
Who is it for?
Agents or developers on the gws CLI that need to fetch one email's body or headers by message ID.
Skip if: Sending or managing email; those live in the broader gws-gmail skill, and auth setup lives in gws-shared.
When should I use this skill?
Gmail: read a message and extract its body or headers.
What you get
The extracted body or headers of a Gmail message, in text, JSON, or HTML form.
- Extracted Gmail message body or headers
By the numbers
- 5 documented flags (--id, --headers, --format, --html, --dry-run)
Files
gmail +read
PREREQUISITE: Read../gws-shared/SKILL.mdfor auth, global flags, and security rules. If missing, rungws generate-skillsto create it.
Read a message and extract its body or headers
Usage
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
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 — Global flags and auth
- gws-gmail — All send, read, and manage email commands
Related skills
Grill MeHave an agent relentlessly pressure-test their plan or design until every decision branch is resolved and shared understanding is reached.645k185kGrill With DocsPressure-test architecture decisions against their live codebase and living documentation before writing production code.547k185k
Lark CalendarLet their coding agents read, create, and manage events inside Lark (Feishu) Calendar directly from natural language instructions.466kLark ContactLet their AI coding agents read and write contacts, send messages, and manage user data inside Lark (Feishu).466kLark ImLet their coding agent send instant notifications, post updates, and receive commands directly inside Lark (Feishu) workspaces.466kLark AttendanceAutomatically fetch and report daily attendance data from Lark (Feishu) into their own tools or agents.465kHow it compares
Use gws-gmail-read to extract message content by ID; use gws-gmail-reply-all or gws-gmail-forward after reading when responding or handing off.
FAQ
What input does gws-gmail-read need?
A required --id (the Gmail message ID); optional flags add headers, choose text/json format, return HTML body, or dry-run the request.
Does it handle HTML-only emails?
Yes. It converts HTML-only messages to plain text automatically and handles multipart/alternative and base64 decoding.
Is Gws Gmail Read safe to install?
skills.sh reports 2 of 3 security scanners passed. Review the Security Audits panel on this page before installing in production.