Gws Gmail Read

This does exactly what you'd expect: grabs a Gmail message by ID and extracts the body text or headers. It automatically converts HTML-only emails to plain text and handles multipart messages and base64 decoding behind the scenes. You'll reach for this when building email processing workflows or debugging message content issues. The JSON output mode makes it easy to pipe into other tools. One nice touch is the dry-run flag so you can see the actual API request before hitting Gmail's servers.

skills.sh installs: 42.1K
GitHub stars: 32.2K
last updated: Aug 21, 2026

View on GitHub

Install

$ npx -y skills add googleworkspace/cli --skill gws-gmail-read --agent claude-code

Installs into .claude/skills of the current project.

Files

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

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.

Details

Repository: github.com/googleworkspace/cli
Categories: CLI & Terminal, Office & Documents