Read Gmail messages and threads using gws CLI. Use this skill when any Founder OS plugin needs to search, list, or retrieve email messages — replaces Gmail MCP server read operations.
From founder-osnpx claudepluginhub thecloudtips/founder-os --plugin founder-osThis skill uses the workspace's default tool permissions.
Designs and optimizes AI agent action spaces, tool definitions, observation formats, error recovery, and context for higher task completion rates.
Enables AI agents to execute x402 payments with per-task budgets, spending controls, and non-custodial wallets via MCP tools. Use when agents pay for APIs, services, or other agents.
Compares coding agents like Claude Code and Aider on custom YAML-defined codebase tasks using git worktrees, measuring pass rate, cost, time, and consistency.
Gmail read operations via gws CLI. Covers searching, listing, and retrieving messages and threads.
gmail.readonly (minimum), gmail.insert for triage# Get unread messages with smart categorization
gws gmail +triage --max 50 --format json
Output: JSON array of messages with id, subject, from, date, snippet, labels.
This is the fastest way to get an inbox overview. Use for P01 Inbox Zero, P02 Daily Briefing, P22 Morning Sync.
# Custom Gmail search query
gws gmail users messages list --params '{"userId":"me","q":"QUERY","maxResults":N}' --format json
Query syntax (same as Gmail search box):
is:unread — unread messagesfrom:user@example.com — from specific senderafter:2026/03/01 before:2026/03/09 — date rangesubject:invoice — subject contains wordhas:attachment — has attachmentslabel:important — specific labelOROutput: JSON with messages array containing {id, threadId} pairs. You need a separate get call for full message content.
# Get complete message with headers and body
gws gmail users messages get --params '{"userId":"me","id":"MSG_ID","format":"full"}' --format json
Output: Full message object with:
payload.headers[] — Subject, From, To, Date, etc.payload.body.data — Base64-encoded body (for simple messages)payload.parts[] — MIME parts (for multipart messages)labelIds[] — Applied labelssnippet — Plain text preview# Get full thread (all messages in conversation)
gws gmail users threads get --params '{"userId":"me","id":"THREAD_ID","format":"full"}' --format json
gws gmail users labels list --params '{"userId":"me"}' --format json
# Step 1: Get message IDs
ids=$(gws gmail users messages list --params '{"userId":"me","q":"is:unread","maxResults":20}' --format json | jq -r '.messages[].id')
# Step 2: Get each message
for id in $ids; do
gws gmail users messages get --params "{\"userId\":\"me\",\"id\":\"$id\",\"format\":\"full\"}" --format json
done
gws gmail users messages list --params '{"userId":"me","q":"from:client@example.com after:2026/03/01","maxResults":10}' --format json
If Gmail is unavailable, return:
{"source": "gmail", "status": "unavailable", "reason": "gws CLI not found or auth expired"}
Continue with other data sources. Never hard-fail a plugin because Gmail is unreachable.