gmail-checker

Send, read, search, and manage Gmail emails via the Gmail REST API. Use when asked to send an email, check inbox, read messages, search mail, reply to emails...

Security Scan

The skill's declared requirements mostly match a Gmail REST integration, but its runtime instructions reference additional sensitive environment variables and behaviors (refresh-token flow, local file attachments, arbitrary web fetching) that are not declared and could be used to access or exfiltrate data.

Purpose & Capability

Name and description match the actions shown in SKILL.md (send/read/search/manage Gmail). Required binaries (curl, jq) and GMAIL_ACCESS_TOKEN are appropriate for calling the Gmail REST API. However, the README also documents an OAuth refresh flow that needs GMAIL_CLIENT_ID, GMAIL_CLIENT_SECRET, and GMAIL_REFRESH_TOKEN — these are not listed in the skill's declared required env vars, which is an inconsistency.

Instruction Scope

SKILL.md instructs the agent to: (a) use an OAuth refresh flow and set GMAIL_ACCESS_TOKEN from curl output (references GMAIL_CLIENT_ID, GMAIL_CLIENT_SECRET, GMAIL_REFRESH_TOKEN), (b) read local file paths for attachments (user-supplied file paths), and (c) perform 'web_research' by calling web_search and fetching arbitrary web pages (xurl/curl). These runtime steps access environment variables and local files beyond the single declared env var and include fetching external URLs — behavior that increases opportunity for unintended data access or exfiltration and is not fully declared.

Install Mechanism

Instruction-only skill with no install spec and no code files. This minimizes disk-written third-party code; risk comes from the runtime instructions rather than an installed binary.

Credentials

Declared required env vars list only GMAIL_ACCESS_TOKEN, which is appropriate. But the documented refresh-token option requires additional sensitive values (GMAIL_CLIENT_ID, GMAIL_CLIENT_SECRET, GMAIL_REFRESH_TOKEN) that the skill uses at runtime but does not declare as required. Those are high-value secrets and should be explicitly declared and justified. The skill also suggests reading attachment file paths (local filesystem access) without detailing safeguards.

Persistence & Privilege

always is false and the skill does not request persistent system configuration or write to other skills' settings. Autonomous invocation is allowed (default) but not combined with elevated privileges in this package.

What to consider before installing

This skill generally does what it says — call the Gmail API via curl — but there are notable inconsistencies and risks you should consider before installing: - Secrets disclosure: The SKILL.md describes a refresh-token flow that uses GMAIL_CLIENT_ID, GMAIL_CLIENT_SECRET, and GMAIL_REFRESH_TOKEN, but those variables are not declared in the skill metadata. If you set them, they are high-value credentials; only provide them if you fully trust the skill and the environment. Prefer creating OAuth credentials with the minimum required scopes and a test account if possible. - Local file access: The skill accepts 'attachments' as file paths. Confirm how attachments are read/encoded and avoid pointing it at directories containing sensitive files. Treat the agent's runtime environment like any process that can read files. - External fetches: The skill's 'web_research' flow instructs fetching arbitrary web pages (xurl/curl). That can leak data (for example, if it fetches pages that include private links) or contact third parties. If you don't want network fetches, request a version of the skill that disables web research. - Lack of declared env vars: Ask the publisher to update the skill metadata to list all environment variables the runtime uses (including client id/secret/refresh token) so you can make an informed decision. - Mitigations: If you proceed, run it with a dedicated Gmail account and OAuth credentials with the narrowest scopes needed; avoid placing permanent creds in global shell profiles; monitor and be prepared to revoke tokens via Google Cloud Console. If you want, I can draft questions to send to the skill author asking them to (1) declare all env vars used, (2) show how attachments are handled, and (3) provide an option to disable web fetching.

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:

Field	Required	Description
to	yes	Recipient email address(es), comma-separated
subject	yes	Email subject line
body	yes	Email body (plain text or HTML)
cc	no	CC recipients
bcc	no	BCC recipients
attachments	no	File paths to attach
research	no	Topic to web-search for enriching the email body

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 <<'MSGEOF'
From: me
To: [e-mail]
Subject: Email subject
Content-Type: text/html; charset="UTF-8"
MIME-Version: 1.0

<html><body>
<p>Email body here.</p>
</body></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:[e-mail] — 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 <<'MSGEOF'
From: me
To: [e-mail]
Subject: Re: Original subject
In-Reply-To: <[e-mail]>
References: <[e-mail]>
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:[e-mail] subject:"Standup notes" body:"Here are today's updates..."

# Check inbox
/gmail inbox

# Search for unread emails from a specific sender
/gmail search "from:[e-mail] 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:[e-mail] subject:"Redis 8 migration plan" --search "Redis 8 breaking changes"

# Mark all unread as read
/gmail read-all