Ready to supercharge your AI agents?

Install any skill in seconds. Free to start, no credit card required.

Get Started Free →

Gmail · LeoYeAI | DecimalAI

Gmail

SkillScore80Maintained

gmail

Access the Gmail API with managed OAuth authentication. Read, send, and manage emails, threads, labels, and drafts.

productivityby LeoYeAI

Links this skill to your agents and keeps it current with the author’s updates.

Automatic

Personal Assistant pack

1 · One-time — install the CLI (docs ↗)

pip install decimalai

2 · Get the skill — writes .claude/skills/gmail/SKILL.md

decimalai skills pull gmail --out .claude/skills/

No CLI? Get the same file — curl · raw file

curl -fsSL --create-dirs -o .claude/skills/gmail/SKILL.md https://app.decimal.ai/s/gmail/SKILL.md

Raw file: /s/gmail/SKILL.md ↗ · machine-readable summary at /s/gmail.json ↗

In productionGlobal

how this skill behaves on real traffic · last 30 days

Runs

all versions · 30d

Eval pass

100%

global

Used when offered

97%

used / offered · all versions

By model· real traffic, every org · 30d — not the benchmark

Model	Eval pass	Runs
gemini-3.6-flash	100%	31

Anonymized aggregate across every org using this skill — proof from real production use, not a demo.

Does this skill help? · Benchmark: with vs. withoutsign in to run this on your agents

22 test cases from the publisher’s eval.yaml · each run twice on gemini-3.6-flash — with the skill injected, then without · last run 52d ago

Yes — +69% lift · at higher cost+114% tokens0% turns73% of whole cases pass with skill (16/22)

Test case	Without → With	Effect	Δ tokens	Δ turns
case-01	✗→✓	▲ Improved	162%	0%
case-02	✗→✓	▲ Improved	49%	0%
case-03	✗→✓	▲ Improved	185%	0%
case-04	✗→✓	▲ Improved	205%	0%
case-05	✗→✓	▲ Improved	49%	0%

Showing 5 of 22 cases

SkillSafety

✓ 3 of 3 passed

Code scan15 of 15 checks clean

0 critical · 0 warning · 0 info — scanner v4 — 7/30/2026

live_secretremote_code_executionreverse_shelldata_exfiltrationssrf_metadataagent_snoopinganti_refusaldestructive_commandsobfuscated_unicodeunicode_homoglyphopaque_blobsuspicious_urltool_overreachtrigger_abuseprompt_injection_phrasing

IntentSafe

LLM judge · does the skill do what it claims

ContentClean

LLM judge · policy & harmful-content review

Source

Imported

LeoYeAI / openclaw-master-skills

skills/gmail/SKILL.md

View on GitHub ↗

License MITImported 8/2/2026Version v1

Skill contents

SKILL.md

Gmail

Access the Gmail API with managed OAuth authentication. Read, send, and manage emails, threads, labels, and drafts.

Quick Start

bash
# List messages
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/google-mail/gmail/v1/users/me/messages?maxResults=10')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Base URL

https://gateway.maton.ai/google-mail/{native-api-path}

Replace {native-api-path} with the actual Gmail API endpoint path. The gateway proxies requests to gmail.googleapis.com and automatically injects your OAuth token.

Authentication

All requests require the Maton API key in the Authorization header:

Authorization: Bearer $MATON_API_KEY

Environment Variable: Set your API key as MATON_API_KEY:

bash
export MATON_API_KEY="YOUR_API_KEY"

Getting Your API Key

Sign in or create an account at maton.ai
Go to maton.ai/settings
Copy your API key

Connection Management

Manage your Google OAuth connections at https://ctrl.maton.ai.

List Connections

bash
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections?app=google-mail&status=ACTIVE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Create Connection

bash
python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'google-mail'}).encode()
req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Get Connection

bash
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Response:

json
{
  "connection": {
    "connection_id": "21fd90f9-5935-43cd-b6c8-bde9d915ca80",
    "status": "ACTIVE",
    "creation_time": "2025-12-08T07:20:53.488460Z",
    "last_updated_time": "2026-01-31T20:03:32.593153Z",
    "url": "https://connect.maton.ai/?session_token=...",
    "app": "google-mail",
    "metadata": {}
  }
}

Open the returned url in a browser to complete OAuth authorization.

Delete Connection

bash
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Specifying Connection

If you have multiple Gmail connections, specify which one to use with the Maton-Connection header:

bash
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/google-mail/gmail/v1/users/me/messages')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', '21fd90f9-5935-43cd-b6c8-bde9d915ca80')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

If omitted, the gateway uses the default (oldest) active connection.

API Reference

List Messages

bash
GET /google-mail/gmail/v1/users/me/messages?maxResults=10

With query filter:

bash
GET /google-mail/gmail/v1/users/me/messages?q=is:unread&maxResults=10

Get Message

bash
GET /google-mail/gmail/v1/users/me/messages/{messageId}

With metadata only:

bash
GET /google-mail/gmail/v1/users/me/messages/{messageId}?format=metadata&metadataHeaders=From&metadataHeaders=Subject&metadataHeaders=Date

Send Message

bash
POST /google-mail/gmail/v1/users/me/messages/send
Content-Type: application/json

{
  "raw": "BASE64_ENCODED_EMAIL"
}

List Labels

bash
GET /google-mail/gmail/v1/users/me/labels

List Threads

bash
GET /google-mail/gmail/v1/users/me/threads?maxResults=10

Get Thread

bash
GET /google-mail/gmail/v1/users/me/threads/{threadId}

Modify Message Labels

bash
POST /google-mail/gmail/v1/users/me/messages/{messageId}/modify
Content-Type: application/json

{
  "addLabelIds": ["STARRED"],
  "removeLabelIds": ["UNREAD"]
}

Trash Message

bash
POST /google-mail/gmail/v1/users/me/messages/{messageId}/trash

Create Draft

bash
POST /google-mail/gmail/v1/users/me/drafts
Content-Type: application/json

{
  "message": {
    "raw": "BASE64URL_ENCODED_EMAIL"
  }
}

Send Draft

bash
POST /google-mail/gmail/v1/users/me/drafts/send
Content-Type: application/json

{
  "id": "{draftId}"
}

Get Profile

bash
GET /google-mail/gmail/v1/users/me/profile

Query Operators

Use in the q parameter:

is:unread - Unread messages
is:starred - Starred messages
from:email@example.com - From specific sender
to:email@example.com - To specific recipient
subject:keyword - Subject contains keyword
after:2024/01/01 - After date
before:2024/12/31 - Before date
has:attachment - Has attachments

Code Examples

JavaScript

javascript
const response = await fetch(
  'https://gateway.maton.ai/google-mail/gmail/v1/users/me/messages?maxResults=10',
  {
    headers: {
      'Authorization': `Bearer ${process.env.MATON_API_KEY}`
    }
  }
);

Python

python
import os
import requests

response = requests.get(
    'https://gateway.maton.ai/google-mail/gmail/v1/users/me/messages',
    headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'},
    params={'maxResults': 10, 'q': 'is:unread'}
)

Notes

Use me as userId for the authenticated user
Message body is base64url encoded in the raw field
Common labels: INBOX, SENT, DRAFT, STARRED, UNREAD, TRASH
IMPORTANT: When using curl commands, use curl -g when URLs contain brackets (fields[], sort[], records[]) to disable glob parsing
IMPORTANT: When piping curl output to jq or other commands, environment variables like $MATON_API_KEY may not expand correctly in some shell environments. You may get "Invalid API key" errors when piping.

Error Handling

| Status | Meaning | |--------|---------| | 400 | Missing Gmail connection | | 401 | Invalid or missing Maton API key | | 429 | Rate limited (10 req/sec per account) | | 4xx/5xx | Passthrough error from Gmail API |

Troubleshooting: API Key Issues

Check that the MATON_API_KEY environment variable is set:

bash
echo $MATON_API_KEY

Verify the API key is valid by listing connections:

bash
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Troubleshooting: Invalid App Name

Ensure your URL path starts with google-mail. For example:

Correct: https://gateway.maton.ai/google-mail/gmail/v1/users/me/messages
Incorrect: https://gateway.maton.ai/gmail/v1/users/me/messages

Resources

Illustrative Want to see what gmail would put in front of your model? Preview the rendered body and check its trigger phrases — no LLM call, no signup.

Latest benchmark · publisher runVerified

7/31/2026, 14:48 UTC · 22 cases

Lift

+69%

85% vs 15%

Agent turns

1.0 vs 1.0

Tokens

+114%

3,890.68 vs 1,821.27

fail → pass · 16fail → fail · 6

Per-case results (22)

Case	Status	Duration (ms)			Turns			Tokens			Tool calls
Case	Status	Without	With	Δ	Without	With	Δ	Without	With	Δ	Without	With	Δ
case-01 Write a Python script that creates an email draft to my boss about the Q3 report. Output the code in a single markdown block and include brief instructions on how to execute it.	fail→pass	12,245	9,715	-21%	1	1	0%	1,835	4,808	+162%	0	0	—
case-02 I need to check my inbox for any unread emails I received from a specific client this week. Please provide a bash script using curl that fetches these emails. Format your response as a step-by-step guide with the script contained in a single code block.	fail→pass	14,587	8,245	-43%	1	1	0%	2,979	4,438	+49%	0	0	—
case-03 I have multiple email accounts linked and need to fetch the mailbox labels for a secondary account. Give me a Node.js code snippet using the fetch API that retrieves the labels for a specific connection ID. Return just the raw code without any explanatory text.	fail→pass	7,883	3,130	-60%	1	1	0%	1,159	3,306	+185%	0	0	—
case-04 I need to send a plain text email to a customer using a Python script. Provide the code to dispatch the message. Assume the email content is already prepared as a string.	fail→pass	8,622	7,221	-16%	1	1	0%	1,403	4,278	+205%	0	0	—
case-05 Write a bash script using curl to retrieve all of my currently active Google Mail integrations from the control plane.	fail→pass	12,392	4,635	-63%	1	1	0%	2,474	3,676	+49%	0	0	—
case-06 I want to authorize a new Google Mail account programmatically. Show me the HTTP request or Python code to initiate this process and get the authorization URL.	fail→pass	15,912	4,813	-70%	1	1	0%	2,398	3,755	+57%	0	0	—
case-07 One of my linked email accounts is no longer needed. Provide a curl command to remove a specific integration ID from the control plane.	fail→pass	6,232	2,549	-59%	1	1	0%	1,145	3,162	+176%	0	0	—
case-08 How do I check the current status and metadata of a specific email integration ID using Python's requests library?	fail→pass	11,150	4,639	-58%	1	1	0%	1,897	3,771	+99%	0	0	—
case-09 I have a specific message ID and I only want to retrieve its headers (specifically From, Subject, and Date) to save bandwidth. Write a curl command to fetch this.	fail→fail	10,099	3,465	-66%	1	1	0%	1,922	3,423	+78%	0	0	—
case-10 An email has been processed by my script and I want to mark it as read and star it. Provide the HTTP request details to update the message.	fail→pass	6,135	4,067	-34%	1	1	0%	1,269	3,635	+186%	0	0	—
case-11 Write a Node.js snippet to move a specific email ID to the trash bin.	fail→pass	9,912	4,221	-57%	1	1	0%	1,828	3,629	+99%	0	0	—
case-12 I have a draft ID that was created earlier. Provide the curl command to actually dispatch this draft to the recipient.	fail→pass	4,819	3,033	-37%	1	1	0%	944	3,323	+252%	0	0	—
case-13 I want to retrieve the 5 most recent email conversations (not just individual messages) from my inbox. Write a Python script to fetch them.	fail→pass	17,905	7,372	-59%	1	1	0%	3,536	4,249	+20%	0	0	—
case-14 Given a specific conversation ID, how do I fetch the full details of that conversation using the fetch API in JavaScript?	fail→pass	7,732	5,678	-27%	1	1	0%	1,484	3,828	+158%	0	0	—
case-15 Write a curl command to retrieve the email address and total message count for the currently authenticated user.	fail→pass	4,879	3,100	-36%	1	1	0%	909	3,327	+266%	0	0	—
case-16 My bulk email processing script is occasionally receiving HTTP 429 errors. What specific threshold is being exceeded and how should I handle it?	fail→pass	13,019	8,708	-33%	1	1	0%	2,363	4,236	+79%	0	0	—
case-17 When making a request to fetch messages, I receive an HTTP 400 error. What does this specific status code indicate in this context?	fail→pass	8,870	5,242	-41%	1	1	0%	1,626	3,775	+132%	0	0	—
case-18 I am trying to use curl to fetch messages with specific fields, but the URL contains square brackets and my shell is throwing an error. How do I fix the curl command?	fail→fail	7,151	4,658	-35%	1	1	0%	1,288	3,496	+171%	0	0	—
case-19 I am constructing the JSON payload to create a new draft. What specific encoding must be applied to the raw email string before sending it in the payload?	fail→fail	8,605	4,337	-50%	1	1	0%	1,524	3,539	+132%	0	0	—
case-20 I need to list the next 10 upcoming events on my primary Google Calendar. Provide a Python script to fetch these events.	fail→fail	10,687	7,271	-32%	1	1	0%	2,328	4,345	+87%	0	0	—
case-21 Write a Node.js script to upload a PDF file to a specific folder in Google Drive.	fail→fail	10,443	13,458	+29%	1	1	0%	2,196	5,792	+164%	0	0	—
case-22 I have an 'email.eml' file saved locally on my disk. Write a Python script to extract the sender, subject, and plain text body from this file.	fail→fail	7,995	5,427	-32%	1	1	0%	1,561	3,804	+144%	0	0	—

These cases were also screened by the skill’s intent / safety pass.See the Trust review ↗Reproduce this benchmark in Colab ↗

How this skill was measured

DecimalAI ran this skill against gemini-3.6-flash twice over the same eval suite — once with the skill loaded and once without — and compared the two runs case by case. 22 cases were attempted. The headline lift of +69 percentage points is the difference between those two pass rates over the 22 comparable cases. 2 cases got worse with the skill loaded, and they are included in that figure.

Model measured: gemini-3.6-flash
Graded by: gemini-3.6-flash
Grading method: judged
Verification: verified
Pass rate without the skill: 15.4%
Pass rate with the skill: 84.6%
Cases attempted: 22
Cases counted toward lift: 22
Cases that regressed: 2
Skill version measured: v1
Run completed: 7/31/2026, 14:48 UTC

Measured example — same prompt, with vs. without the skill · from the benchmark run · case case-01

Prompt

Write a Python script that creates an email draft to my boss about the Q3 report. Output the code in a single markdown block and include brief instructions on how to execute it.

Without the skill loaded, the model failed this case. With it loaded, the same prompt on the same model passed. This is one improved case from the latest verified run; every case, including any that regressed, is in the table above.

Show both answers

SkillScore blends 4 signals3 of 4 complete

BenchmarkPass rate WITH skill on a verified run85

Live evalPass rate on real evaluated traces100%

AI ratingNeeds ≥10 rated traces

AdoptionBreadth of real use across orgs40

Backed by 3 of 4 signals — each added signal makes the score more robust.

Verified on gemini-3.6-flash · re-tested 52 days ago

Other measured skills in the registry, with their headline benchmark lift.

Ready to supercharge your AI agents?

Gmail

SkillSafety

Source

Gmail

Quick Start

Base URL

Authentication

Getting Your API Key

Connection Management

List Connections

Create Connection

Get Connection

Delete Connection

Specifying Connection

API Reference

List Messages

Get Message

Send Message

List Labels

List Threads

Get Thread

Modify Message Labels

Trash Message

Create Draft

Send Draft

Get Profile

Query Operators

Code Examples

JavaScript

Python

Notes

Error Handling

Troubleshooting: API Key Issues

Troubleshooting: Invalid App Name

Resources

How this skill was measured

Measured example — same prompt, with vs. without the skill · from the benchmark run · case case-01

Related skills