# Gmail Guide for ClawkAI Agents Use this guide to let your agent read and send Gmail through ClawkAI proxy endpoints. This is action based and works without installing custom skills on Hermes runtime. --- ## 1) Prerequisites Before any mail request: 1. In ClawkAI dashboard, open `Connections`. 2. Connect Google account. 3. Pick permission mode: - `Read & send` - `Read` - `Send` If Gmail is not connected, calls will fail with auth errors. --- ## 2) Auth and base URL Use gateway token auth for all calls. - Base URL: `https://api.clawkai.com/v1` - Header: `Authorization: Bearer ` - Content type for POST: `application/json` --- ## 3) Endpoints ### List messages - `GET /mail/list?query=&max=<1..20>` Example: ```bash curl -sS "https://api.clawkai.com/v1/mail/list?query=from:alerts&max=5" \ -H "Authorization: Bearer $GATEWAY_TOKEN" ``` ### Read one message - `GET /mail/message/` Example: ```bash curl -sS "https://api.clawkai.com/v1/mail/message/$MESSAGE_ID" \ -H "Authorization: Bearer $GATEWAY_TOKEN" ``` ### Send message - `POST /mail/send` - Body: `to`, `subject`, and one of `body` (text) or `html` (rich email), optional `from` Example: ```bash curl -sS "https://api.clawkai.com/v1/mail/send" \ -H "Authorization: Bearer $GATEWAY_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "to": "user@example.com", "subject": "Status update", "body": "Hello, here is your update." }' ``` ### Send rich HTML/CSS email ```bash curl -sS "https://api.clawkai.com/v1/mail/send" \ -H "Authorization: Bearer $GATEWAY_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "to": "user@example.com", "subject": "Weekly Report", "html": "

Weekly Report

All systems are healthy.

" }' ``` --- ## 4) Python helper ```python import os import json import urllib.parse import urllib.request BASE = "https://api.clawkai.com/v1" TOKEN = os.environ["GATEWAY_TOKEN"] def req(path, method="GET", payload=None): url = f"{BASE}{path}" headers = {"Authorization": f"Bearer {TOKEN}"} data = None if payload is not None: headers["Content-Type"] = "application/json" data = json.dumps(payload).encode("utf-8") r = urllib.request.Request(url, data=data, headers=headers, method=method) with urllib.request.urlopen(r, timeout=60) as resp: return json.loads(resp.read().decode("utf-8")) def list_mail(query="", max_results=5): q = urllib.parse.quote(query or "") return req(f"/mail/list?query={q}&max={max_results}") def get_mail(message_id): mid = urllib.parse.quote(message_id) return req(f"/mail/message/{mid}") def send_mail(to, subject, body=None, html=None, from_addr=None): payload = {"to": to, "subject": subject} if body: payload["body"] = body if html: payload["html"] = html if from_addr: payload["from"] = from_addr return req("/mail/send", method="POST", payload=payload) ``` --- ## 5) Error handling Common API error codes: - `gmail_not_connected`: user must connect Gmail in dashboard - `gmail_permission_missing`: selected mode does not allow this operation - `gmail_token_invalid`: reconnect Gmail - `gmail_token_refresh_failed`: reconnect Gmail Typical statuses: - `409` connection/auth issues - `403` permission mismatch - `502` upstream Gmail API failure --- ## 6) Recommended runtime behavior When handling a mail task: 1. Call `/mail/list` first for context. 2. If user references a specific message, call `/mail/message/:id`. 3. Before sending, confirm recipient and subject. 4. Send with `/mail/send`. 5. Return the resulting `id` and `threadId` to the user.