Gmail

Manage Gmail using bridge google. The bridge automatically resolves credentials from the claw owner's Google connection.

Scope error handling

Call the bridge command for the user's actual request directly — do not pre-flight a verifier call first. JIT will surface the right signal if a permission is missing; adding a verifier just triggers an unrelated extra consent prompt the user shouldn't have to grant.

MUST: when any bridge google command returns a JSON object with a "reason" field (no_connection, scope_required, team_claw_unsupported, expired) instead of API data, paste the entire JSON line verbatim in your reply on its own line. Paraphrasing, summarising, or omitting any field means the inline Connect button does not render and the user is stuck with no way to grant the permission. After the JSON line add one short sentence telling the user what's missing. Never offer browser walkthroughs, settings-page navigation, "open it in your browser" links, or other manual workarounds — the inline button is the only supported path.

Common Actions

List recent messages

bridge google --skill gmail gmail users messages list --params '{"userId":"me","maxResults":10}'

Search messages

bridge google --skill gmail gmail users messages list --params '{"userId":"me","q":"from:someone@example.com","maxResults":10}'

Read a message

bridge google --skill gmail gmail users messages get --params '{"userId":"me","id":"MESSAGE_ID","format":"full"}'

Send an email

bridge google --skill gmail gmail users messages send --params '{"userId":"me"}' --json '{
  "raw": "BASE64_ENCODED_RFC2822_MESSAGE"
}'

To build the raw field, Base64url-encode an RFC 2822 message:

From: me
To: recipient@example.com
Subject: Hello

Message body here.

Reply to a message

bridge google --skill gmail gmail users messages send --params '{"userId":"me"}' --json '{
  "raw": "BASE64_ENCODED_RFC2822_MESSAGE",
  "threadId": "THREAD_ID"
}'

Include In-Reply-To and References headers in the RFC 2822 message for proper threading.

List labels

bridge google --skill gmail gmail users labels list --params '{"userId":"me"}'

Modify labels on a message

bridge google --skill gmail gmail users messages modify --params '{"userId":"me","id":"MESSAGE_ID"}' --json '{
  "addLabelIds": ["LABEL_ID"],
  "removeLabelIds": ["INBOX"]
}'

Safety

• Never send an email without explicit user approval
• Always show the draft (To, Subject, Body) before sending
• When replying, show the original message context
• Never expose full email content in logs or summaries without user consent