Dbochman/gws-gmail

Gmail (gws)

Access Gmail via the gws CLI at /opt/homebrew/bin/gws. Credentials are AES-256-GCM encrypted at ~/.config/gws/.

Read references/gws-cli.md before selecting an account, changing authentication, or executing a write.

Accounts

| Account | Owner | Raw Gmail API selector | |---------|-------|-------------------------| | ${DYLAN_EMAIL} | Dylan | GOOGLE_WORKSPACE_CLI_ACCOUNT=${DYLAN_EMAIL} | | ${JULIA_EMAIL} | Julia | GOOGLE_WORKSPACE_CLI_ACCOUNT=${JULIA_EMAIL} | | ${STARMARKET_GMAIL} | Dylan (spam) | GOOGLE_WORKSPACE_CLI_ACCOUNT=${STARMARKET_GMAIL} | | ${OPENCLAW_EMAIL} | OpenClaw | GOOGLE_WORKSPACE_CLI_ACCOUNT=${OPENCLAW_EMAIL} |

When Dylan asks about "my email", use default. When he says "Julia's email", use her account.

Command Pattern

Raw Gmail API commands follow:

GOOGLE_WORKSPACE_CLI_ACCOUNT=<email> gws gmail <resource> <method> [--params '<JSON>'] [--json '<JSON>']

• --params = URL/query parameters (userId, q, maxResults, etc.)
• --json = request body (for send, modify, etc.)

With pinned GWS 0.4.4, do not use --account on raw API resource commands; that flag is not reliably routed and can return No credentials provided. Use GOOGLE_WORKSPACE_CLI_ACCOUNT instead. Reserve --account for authentication subcommands that explicitly list it in gws auth --help.

Important: Most Gmail endpoints require "userId": "me" in params.

Search Messages

# Unread messages
gws gmail users messages list --params '{
  "userId": "me",
  "q": "is:unread",
  "maxResults": 10
}'

# From a specific sender
gws gmail users messages list --params '{
  "userId": "me",
  "q": "from:[email protected]"
}'

# With attachments, recent
gws gmail users messages list --params '{
  "userId": "me",
  "q": "has:attachment newer_than:7d"
}'

# Julia's unread
GOOGLE_WORKSPACE_CLI_ACCOUNT=${JULIA_EMAIL} gws gmail users messages list --params '{
  "userId": "me",
  "q": "is:unread",
  "maxResults": 10
}'

Common Gmail Query Syntax

| Query | Meaning | |-------|---------| | is:unread | Unread messages | | is:starred | Starred messages | | is:important | Important messages | | in:inbox | Messages in inbox | | in:sent | Sent messages | | from:[email protected] | From specific sender | | to:[email protected] | To specific recipient | | subject:keyword | Subject contains keyword | | has:attachment | Has attachments | | filename:pdf | Has PDF attachment | | after:2026/01/01 | After date | | before:2026/02/01 | Before date | | newer_than:7d | Newer than 7 days | | older_than:1m | Older than 1 month | | label:work | Has label | | category:promotions | In category |

Combine queries: from:[email protected] is:unread after:2026/01/01

Get a Single Message

# Full message with body
gws gmail users messages get --params '{
  "userId": "me",
  "id": "<messageId>",
  "format": "full"
}'

# Metadata only (headers)
gws gmail users messages get --params '{
  "userId": "me",
  "id": "<messageId>",
  "format": "metadata"
}'

With pinned GWS 0.4.4, passing metadataHeaders through --params can return payload without a headers array. Omit that parameter, request metadata, and filter the returned headers locally. Do not pipe an API error object into jq; check the command status and .error first.

Response shape — where headers actually live

The metadata response does NOT put headers at the top level. They're nested under payload.headers as an array of {name, value} objects:

{
  "id": "...",
  "internalDate": "1777719291000",
  "labelIds": ["INBOX", ...],
  "payload": {
    "headers": [
      {"name": "From", "value": "..."},
      {"name": "Subject", "value": "..."},
      {"name": "Date", "value": "..."}
    ]
  }
}

To extract them flat, pipe through jq:

if ! out=$(gws gmail users messages get --params '{"userId":"me","id":"<id>","format":"metadata"}' 2>&1); then
  echo "Gmail metadata unavailable" >&2
  exit 1
fi
jq -e '(.error? == null) and (.payload.headers | type == "array")' <<<"$out" >/dev/null || {
  echo "Gmail metadata unavailable" >&2
  exit 1
}
jq '.payload.headers | map(select(.name == "From" or .name == "Subject" or .name == "Date") | {(.name): .value}) | add' <<<"$out"
# → {"From":"[email protected]","Subject":"...","Date":"..."}

For batch summaries (e.g., morning briefing), loop a list call's IDs through this pattern and concat — don't fall back to format: "full" snippets, which is slow and lossy.

Get a Thread

gws gmail users threads get --params '{
  "userId": "me",
  "id": "<threadId>",
  "format": "full"
}'

Send a Message

Messages must be base64url-encoded RFC 2822 format.

IMPORTANT: Use Python base64.urlsafe_b64encode to encode the raw email. Do NOT use shell printf | base64 | tr — it corrupts ! to \! and mangles special characters.

# Step 1: Build base64url payload with Python (safe for all characters)
RAW_B64=$(python3 -c "
import base64
msg = 'From: [email protected]\r\nTo: [email protected]\r\nSubject: Hello\r\nContent-Type: text/plain; charset=utf-8\r\n\r\nMessage body here!'
print(base64.urlsafe_b64encode(msg.encode()).decode().rstrip('='))
")

# Step 2: Send via gws
gws gmail users messages send --params '{"userId": "me"}' \
  --json "{\"raw\":\"${RAW_B64}\"}"

# Reply to a thread (add threadId, In-Reply-To, References headers)
RAW_B64=$(python3 -c "
import base64
msg = 'From: [email protected]\r\nTo: [email protected]\r\nSubject: Re: Original Subject\r\nIn-Reply-To: <original-message-id>\r\nReferences: <original-message-id>\r\nContent-Type: text/plain; charset=utf-8\r\n\r\nReply body here'
print(base64.urlsafe_b64encode(msg.encode()).decode().rstrip('='))
")
gws gmail users messages send --params '{"userId": "me"}' \
  --json "{\"threadId\":\"<threadId>\",\"raw\":\"${RAW_B64}\"}"

For HTML emails, use Content-Type: text/html; charset=utf-8 in the headers.

Drafts

# List drafts
gws gmail users drafts list --params '{"userId": "me"}'

# Create a draft (use Python base64 pattern from Send section)
RAW_B64=$(python3 -c "
import base64
msg = 'To: [email protected]\r\nSubject: Draft\r\nContent-Type: text/plain; charset=utf-8\r\n\r\nDraft body'
print(base64.urlsafe_b64encode(msg.encode()).decode().rstrip('='))
")
gws gmail users drafts create --params '{"userId": "me"}' \
  --json "{\"message\":{\"raw\":\"${RAW_B64}\"}}"

# Send a draft
gws gmail users drafts send --params '{"userId": "me"}' --json '{
  "id": "<draftId>"
}'

# Delete a draft
gws gmail users drafts delete --params '{"userId": "me", "id": "<draftId>"}'

Labels

# List all labels
gws gmail users labels list --params '{"userId": "me"}'

# Create a label
gws gmail users labels create --params '{"userId": "me"}' --json '{
  "name": "OpenClaw/NewLabel",
  "labelListVisibility": "labelShow",
  "messageListVisibility": "show"
}'

# Get label details
gws gmail users labels get --params '{"userId": "me", "id": "<labelId>"}'

Modify Message Labels

# Mark as read (remove UNREAD)
gws gmail users messages modify --params '{"userId": "me", "id": "<messageId>"}' --json '{
  "removeLabelIds": ["UNREAD"]
}'

# Star a message
gws gmail users messages modify --params '{"userId": "me", "id": "<messageId>"}' --json '{
  "addLabelIds": ["STARRED"]
}'

# Archive (remove from INBOX)
gws gmail users messages modify --params '{"userId": "me", "id": "<messageId>"}' --json '{
  "removeLabelIds": ["INBOX"]
}'

# Apply custom label
gws gmail users messages modify --params '{"userId": "me", "id": "<messageId>"}' --json '{
  "addLabelIds": ["<labelId>"]
}'

Batch Modify

gws gmail users messages batchModify --params '{"userId": "me"}' --json '{
  "ids": ["<msgId1>", "<msgId2>"],
  "addLabelIds": ["STARRED"],
  "removeLabelIds": ["UNREAD"]
}'

Trash / Delete

# Trash (recoverable)
gws gmail users messages trash --params '{"userId": "me", "id": "<messageId>"}'

# Permanent delete (irreversible!)
gws gmail users messages delete --params '{"userId": "me", "id": "<messageId>"}'

Thread Operations

# List threads
gws gmail users threads list --params '{
  "userId": "me",
  "q": "is:unread",
  "maxResults": 10
}'

# Modify thread labels
gws gmail users threads modify --params '{"userId": "me", "id": "<threadId>"}' --json '{
  "addLabelIds": ["STARRED"],
  "removeLabelIds": ["UNREAD"]
}'

# Trash entire thread
gws gmail users threads trash --params '{"userId": "me", "id": "<threadId>"}'

Attachments

# Get attachment (returns base64 data)
gws gmail users messages attachments get --params '{
  "userId": "me",
  "messageId": "<messageId>",
  "id": "<attachmentId>"
}'

Settings

# Vacation responder
gws gmail users settings getVacation --params '{"userId": "me"}'

# Filters
gws gmail users settings filters list --params '{"userId": "me"}'

# Forwarding
gws gmail users settings forwardingAddresses list --params '{"userId": "me"}'

# Send-as aliases
gws gmail users settings sendAs list --params '{"userId": "me"}'

API Schema

For any endpoint, check available parameters:

gws schema gmail.users.messages.list
gws schema gmail.users.messages.send
gws schema gmail.users.threads.get

Automated Inbox Management (Julia)

Julia's inbox automation is split into two daily cron jobs:

• Silent Triage (6:45 AM ET): categorizes and labels mail, creates guarded reply drafts, resolves read state, archives stale read mail, and conservatively trashes clear spam; produces a JSON handoff without delivering a message.
• Read-Only Briefing (7 AM ET): combines that handoff with Calendar and household summaries, then delivers the concise briefing to Julia via iMessage without mutating Gmail.

OpenClaw Labels (Julia's account)

| Label | Purpose | |-------|---------| | OpenClaw/Urgent | Time-sensitive, needs immediate attention | | OpenClaw/Action | Requires response or action from Julia | | OpenClaw/FYI | Informational, no action needed | | OpenClaw/Financial | Bills, bank alerts, transactions | | OpenClaw/Shopping | Orders, shipping, receipts | | OpenClaw/Newsletters | Subscriptions, digests, promotions | | OpenClaw/Social | Social media notifications, invites |

CRITICAL: Sending Emails

NEVER send an email unless the user has explicitly asked you to send it. Drafting an email is not permission to send it. Approving a draft is not permission to send it. The user must clearly and unambiguously instruct you to send before you call the send endpoint. When in doubt, ask. This applies to all accounts and all recipients — no exceptions.

Notes

• Only use the gws CLI for Gmail — do NOT use himalaya, mutt, mail, or any other email CLI. The gws CLI handles multi-account auth and is the only supported tool.
• Default account: ${DYLAN_EMAIL}
• Always check inbox/unread first before reporting on emails
• gws outputs JSON by default — parse directly or pipe through jq
• Thread endpoints group messages into conversations; message endpoints return individual messages
• The raw field for send/drafts uses base64url encoding — always use Python base64.urlsafe_b64encode (shell printf | base64 | tr corrupts ! and other special chars)
• With GWS 0.4.4, use format: "metadata" without metadataHeaders, validate the response, and select only the needed headers locally