Feature request: Gmail +read helper for extracting message body as plain text

[xealot]

Problem

When an AI agent needs to read the content of Gmail messages (e.g., to triage an inbox, summarize emails, or decide on actions), it must use the raw API:

gws gmail users messages get --params '{"userId": "me", "id": "...", "format": "full"}'

This returns the entire message payload including:

• All email headers (Received, DKIM-Signature, ARC chains, SPF, etc.)
• Base64-encoded MIME parts
• Multipart boundaries and nested structure
• Inline image attachments

For a typical email, this produces 10–60KB of JSON, most of which is noise. The agent then has to locate the correct MIME part, base64-decode it, and extract readable text — all of which is error-prone and wastes context window.

By contrast, +triage cleanly abstracts listing messages, but there is no equivalent for reading a single message body.

Proposal

Add a gws gmail +read helper that extracts the human-readable body from a message:

# Read a message body as plain text
gws gmail +read --id <message-id>

# Read with metadata (from, to, subject, date)
gws gmail +read --id <message-id> --headers

# JSON output for agent consumption
gws gmail +read --id <message-id> --format json

The helper would:

1. Fetch the message via users.messages.get
2. Walk the MIME tree to find the text/plain part (or fall back to text/html → stripped text)
3. Base64-decode and return clean, readable content
4. Optionally include key headers (From, To, Subject, Date, Cc)

Example JSON output

{
  "id": "19ce2251577a09ea",
  "from": "Jira automation <automation@squarespace.atlassian.net>",
  "to": "gvilches@squarespace.com",
  "cc": "bkimmel@squarespace.com, tlong@squarespace.com",
  "subject": "[ACTION REQUIRED] Your COE violates 14-Day Incident SLA",
  "date": "Thu, 12 Mar 2026 13:03:25 +0000",
  "body": "George Vilches,\n\nAs the current Assignee for the Incident ticket COE-5367..."
}

Why this matters for agents

+triage answers "what's in my inbox?" but agents immediately need to follow up with "what does this email say?" to make decisions (e.g., does this need a reply? is this actionable?). Today that requires a raw API call that returns massive payloads full of transport headers and encoded content. This is exactly the kind of complexity that helpers are designed to abstract — similar to how +send abstracts RFC 2822 encoding.

The helpers README states helpers should be added when they "abstract away significant complexity" — MIME tree walking and base64 decoding for readable text extraction qualifies.