gws-gmail-read
googleworkspace/cli
Read Gmail messages and extract body or headers with automatic HTML-to-text conversion.
What is gws-gmail-read?
Retrieves a specific Gmail message by ID and extracts its content as plain text or HTML, with optional header information. Use this when you need to programmatically access email message bodies or metadata from Gmail.
- Extract message body in plain text or HTML format
- Include email headers (From, To, Subject, Date) in output
- Automatically convert HTML-only messages to plain text
- Handle multipart/alternative and base64 decoding
- Output results in text or JSON format
- Preview requests with dry-run mode before execution
How to install gws-gmail-read
npx skills add null --skill gws-gmail-read- gws CLI installed and configured
- Google Workspace account with Gmail enabled
- Gmail message ID (obtainable from gws-gmail-list or similar)
- Authentication configured per gws-shared/SKILL.md
How to use gws-gmail-read
- 1.Install the skill: npx skills add null --skill gws-gmail-read
- 2.Obtain the Gmail message ID you want to read
- 3.Run gws gmail +read --id <MESSAGE_ID> to retrieve the message body
- 4.Add --headers flag to include From, To, Subject, and Date fields
- 5.Use --format json to parse output programmatically
- 6.Use --html flag if you need the HTML version instead of plain text
- 7.Use --dry-run to preview the request before executing
Use cases
- Retrieve and process email content for automation workflows
- Extract sender and recipient information from specific messages
- Convert HTML emails to plain text for analysis or logging
- Build email parsing pipelines that integrate with other tools
- Audit or archive email content programmatically
- Automation engineers building email workflows
- DevOps professionals managing email-based processes
- Integration specialists connecting Gmail to other systems
- Developers building email processing applications
gws-gmail-read FAQ
Message IDs can be obtained from gws-gmail-list or other Gmail listing commands. They are unique identifiers assigned by Gmail to each message.
The skill automatically converts HTML-only messages to plain text format by default. Use --html flag if you need the original HTML instead.
The --headers flag includes headers in the output alongside the body. There is no flag to extract headers only; use --format json and parse the output if you need selective extraction.
Two formats are supported: text (default, human-readable) and json (machine-parseable). Use --format json with tools like jq for advanced filtering.
Yes, it requires proper Google Workspace authentication configured via gws-shared. Refer to gws-shared/SKILL.md for auth setup and security rules.
Full instructions (SKILL.md)
Source of truth, from googleworkspace/cli.
name: gws-gmail-read description: "Gmail: Read a message and extract its body or headers." metadata: version: 0.22.5 openclaw: category: "productivity" requires: bins: - gws cliHelp: "gws gmail +read --help"
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
More from googleworkspace/cli and the wider catalog.
gws-gmail
Send, read, and manage Gmail emails via Google Workspace CLI.
gws-drive
Manage Google Drive files, folders, and shared drives via CLI.
gws-docs
Read and write Google Docs via command line.
gws-calendar
Manage Google Calendar events, calendars, and access control via CLI.
gws-sheets
Read and write Google Sheets spreadsheets via CLI.
gws-gmail-send
Send emails via Gmail with attachments, CC/BCC, HTML support, and draft options.