Gmail Skill

Send, read, search, reply, and manage Gmail directly from OpenClaw.

Setup

Option 1: OAuth2 Access Token (recommended)

1. Create OAuth2 credentials at https://console.cloud.google.com/apis/credentials
2. Enable the Gmail API at https://console.cloud.google.com/apis/library/gmail.googleapis.com
3. Obtain an access token via OAuth2 flow with scopes:
   • https://www.googleapis.com/auth/gmail.send
   • https://www.googleapis.com/auth/gmail.readonly
   • https://www.googleapis.com/auth/gmail.modify
4. Set the environment variable:

   export GMAIL_ACCESS_TOKEN="your-access-token"
   

Option 2: Refresh Token (long-lived)

If you have a refresh token, set these additional variables:

export GMAIL_CLIENT_ID="your-client-id"
export GMAIL_CLIENT_SECRET="your-client-secret"
export GMAIL_REFRESH_TOKEN="your-refresh-token"

All API calls use Bearer auth:

curl -s -H "Authorization: Bearer $GMAIL_ACCESS_TOKEN" \
  "https://gmail.googleapis.com/gmail/v1/users/me/..."

Token Refresh

If GMAIL_REFRESH_TOKEN is set, refresh the access token before any API call:

GMAIL_ACCESS_TOKEN=$(curl -s -X POST "https://oauth2.googleapis.com/token" \
  -d "client_id=$GMAIL_CLIENT_ID" \
  -d "client_secret=$GMAIL_CLIENT_SECRET" \
  -d "refresh_token=$GMAIL_REFRESH_TOKEN" \
  -d "grant_type=refresh_token" | jq -r '.access_token')

Commands

Send an Email

Parse the user's request for:

Web Research (if applicable)

If the user wants research-informed content:

1. Use web_search to find relevant information.
2. Fetch key pages with xurl or curl for details.
3. Incorporate findings into the email body naturally.

Compose and Send

Build a raw RFC 2822 message and base64url-encode it:

# Build raw message
RAW_MESSAGE=$(cat \x3C\x3C'MSGEOF'
From: me
To: [email protected]
Subject: Email subject
Content-Type: text/html; charset="UTF-8"
MIME-Version: 1.0

\x3Chtml>\x3Cbody>
\x3Cp>Email body here.\x3C/p>
\x3C/body>\x3C/html>
MSGEOF
)

# Base64url encode (no padding, URL-safe)
ENCODED=$(echo -n "$RAW_MESSAGE" | base64 -w 0 | tr '+/' '-_' | tr -d '=')

# Send
curl -s -X POST \
  -H "Authorization: Bearer $GMAIL_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  "https://gmail.googleapis.com/gmail/v1/users/me/messages/send" \
  -d "{\"raw\": \"$ENCODED\"}"

Extract the message ID from the response and report success.

Read / Check Inbox

List recent messages:

# List latest messages (default 10)
curl -s -H "Authorization: Bearer $GMAIL_ACCESS_TOKEN" \
  "https://gmail.googleapis.com/gmail/v1/users/me/messages?maxResults=10&labelIds=INBOX"

For each message, fetch full details:

curl -s -H "Authorization: Bearer $GMAIL_ACCESS_TOKEN" \
  "https://gmail.googleapis.com/gmail/v1/users/me/messages/{MESSAGE_ID}?format=full"

Extract and display:

• From: sender
• Subject: subject line
• Date: when received
• Snippet: preview text
• Body: decoded from base64 (plain text part preferred)

Decode the body:

# Extract plain text body from payload parts
BODY=$(echo "$RESPONSE" | jq -r '
  .payload.parts[]? |
  select(.mimeType == "text/plain") |
  .body.data' | base64 -d 2>/dev/null)

# Fallback: single-part message
if [ -z "$BODY" ]; then
  BODY=$(echo "$RESPONSE" | jq -r '.payload.body.data' | base64 -d 2>/dev/null)
fi

Search Emails

# Search with Gmail query syntax
curl -s -H "Authorization: Bearer $GMAIL_ACCESS_TOKEN" \
  "https://gmail.googleapis.com/gmail/v1/users/me/messages?q=QUERY&maxResults=10"

Gmail query examples:

• from:[email protected] — from a specific sender
• subject:invoice — subject contains "invoice"
• is:unread — unread messages
• after:2026/01/01 before:2026/03/01 — date range
• has:attachment filename:pdf — PDFs attached
• label:important — labeled important

Fetch and display matching messages using the same read flow above.

Reply to an Email

1. Fetch the original message to get threadId, Message-ID header, and sender.
2. Build the reply with proper headers:

RAW_REPLY=$(cat \x3C\x3C'MSGEOF'
From: me
To: [email protected]
Subject: Re: Original subject
In-Reply-To: \[email protected]>
References: \[email protected]>
Content-Type: text/plain; charset="UTF-8"
MIME-Version: 1.0

Reply body here.
MSGEOF
)

ENCODED=$(echo -n "$RAW_REPLY" | base64 -w 0 | tr '+/' '-_' | tr -d '=')

curl -s -X POST \
  -H "Authorization: Bearer $GMAIL_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  "https://gmail.googleapis.com/gmail/v1/users/me/messages/send" \
  -d "{\"raw\": \"$ENCODED\", \"threadId\": \"THREAD_ID\"}"

Draft an Email

Create a draft without sending:

ENCODED=$(echo -n "$RAW_MESSAGE" | base64 -w 0 | tr '+/' '-_' | tr -d '=')

curl -s -X POST \
  -H "Authorization: Bearer $GMAIL_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  "https://gmail.googleapis.com/gmail/v1/users/me/drafts" \
  -d "{\"message\": {\"raw\": \"$ENCODED\"}}"

Report the draft ID so the user can review it in Gmail before sending.

Manage Labels

# List all labels
curl -s -H "Authorization: Bearer $GMAIL_ACCESS_TOKEN" \
  "https://gmail.googleapis.com/gmail/v1/users/me/labels" | jq '.labels[] | {name, id}'

# Add label to a message
curl -s -X POST \
  -H "Authorization: Bearer $GMAIL_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  "https://gmail.googleapis.com/gmail/v1/users/me/messages/{MESSAGE_ID}/modify" \
  -d '{"addLabelIds": ["LABEL_ID"]}'

# Remove label
curl -s -X POST \
  -H "Authorization: Bearer $GMAIL_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  "https://gmail.googleapis.com/gmail/v1/users/me/messages/{MESSAGE_ID}/modify" \
  -d '{"removeLabelIds": ["LABEL_ID"]}'

# Mark as read
curl -s -X POST \
  -H "Authorization: Bearer $GMAIL_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  "https://gmail.googleapis.com/gmail/v1/users/me/messages/{MESSAGE_ID}/modify" \
  -d '{"removeLabelIds": ["UNREAD"]}'

Network Policy

To use this skill inside NemoClaw's sandbox, add a Gmail network policy preset. Create or add to your sandbox policy:

network_policies:
  google_gmail:
    name: google_gmail
    endpoints:
      - host: gmail.googleapis.com
        port: 443
        protocol: rest
        enforcement: enforce
        tls: terminate
        rules:
          - allow: { method: GET, path: "/**" }
          - allow: { method: POST, path: "/**" }
      - host: oauth2.googleapis.com
        port: 443
        protocol: rest
        enforcement: enforce
        tls: terminate
        rules:
          - allow: { method: POST, path: "/token" }
      - host: accounts.google.com
        port: 443
        protocol: rest
        enforcement: enforce
        tls: terminate
        rules:
          - allow: { method: GET, path: "/**" }
          - allow: { method: POST, path: "/**" }

Notes

• Gmail API rate limit: 250 quota units per second per user.
• Sending has a daily limit of 2,000 messages for Google Workspace, 500 for free Gmail.
• Access tokens expire after ~1 hour. Use refresh token flow for long-running sessions.
• Attachments require multipart MIME encoding — for large files, use the resumable upload endpoint.

Examples

# Send a simple email
/gmail send to:[email protected] subject:"Standup notes" body:"Here are today's updates..."

# Check inbox
/gmail inbox

# Search for unread emails from a specific sender
/gmail search "from:[email protected] is:unread"

# Reply to the latest email
/gmail reply latest "Thanks, I'll look into this."

# Draft an email with web research
/gmail draft to:[email protected] subject:"Redis 8 migration plan" --search "Redis 8 breaking changes"

# Mark all unread as read
/gmail read-all