gmailGmail API integration with managed OAuth. Read, send, and manage emails, threads, labels, and drafts. Use this skill when users want to interact with Gmail. For other third party apps, use the api-gateway skill (https://clawhub.ai/byungkyu/api-gateway).
Install via ClawdBot CLI:
clawdbot install byungkyu/gmailAccess the Gmail API with managed OAuth authentication. Read, send, and manage emails, threads, labels, and drafts.
# 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))
EOFhttps://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.
All requests require the Maton API key in the Authorization header:
Authorization: Bearer $MATON_API_KEYEnvironment Variable: Set your API key as MATON_API_KEY:
export MATON_API_KEY="YOUR_API_KEY"Manage your Google OAuth connections at https://ctrl.maton.ai.
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))
EOFpython <<'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))
EOFpython <<'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))
EOFResponse:
{
"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.
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))
EOFIf you have multiple Gmail connections, specify which one to use with the Maton-Connection header:
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))
EOFIf omitted, the gateway uses the default (oldest) active connection.
GET /google-mail/gmail/v1/users/me/messages?maxResults=10With query filter:
GET /google-mail/gmail/v1/users/me/messages?q=is:unread&maxResults=10GET /google-mail/gmail/v1/users/me/messages/{messageId}With metadata only:
GET /google-mail/gmail/v1/users/me/messages/{messageId}?format=metadata&metadataHeaders=From&metadataHeaders=Subject&metadataHeaders=DatePOST /google-mail/gmail/v1/users/me/messages/send
Content-Type: application/json
{
"raw": "BASE64_ENCODED_EMAIL"
}GET /google-mail/gmail/v1/users/me/labelsGET /google-mail/gmail/v1/users/me/threads?maxResults=10GET /google-mail/gmail/v1/users/me/threads/{threadId}POST /google-mail/gmail/v1/users/me/messages/{messageId}/modify
Content-Type: application/json
{
"addLabelIds": ["STARRED"],
"removeLabelIds": ["UNREAD"]
}POST /google-mail/gmail/v1/users/me/messages/{messageId}/trashPOST /google-mail/gmail/v1/users/me/drafts
Content-Type: application/json
{
"message": {
"raw": "BASE64URL_ENCODED_EMAIL"
}
}POST /google-mail/gmail/v1/users/me/drafts/send
Content-Type: application/json
{
"id": "{draftId}"
}GET /google-mail/gmail/v1/users/me/profileUse in the q parameter:
is:unread - Unread messagesis:starred - Starred messagesfrom:email@example.com - From specific senderto:email@example.com - To specific recipientsubject:keyword - Subject contains keywordafter:2024/01/01 - After datebefore:2024/12/31 - Before datehas:attachment - Has attachmentsconst response = await fetch(
'https://gateway.maton.ai/google-mail/gmail/v1/users/me/messages?maxResults=10',
{
headers: {
'Authorization': `Bearer ${process.env.MATON_API_KEY}`
}
}
);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'}
)me as userId for the authenticated userraw fieldINBOX, SENT, DRAFT, STARRED, UNREAD, TRASHcurl -g when URLs contain brackets (fields[], sort[], records[]) to disable glob parsingjq 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.| 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 |
MATON_API_KEY environment variable is set:echo $MATON_API_KEYpython <<'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))
EOFgoogle-mail. For example:https://gateway.maton.ai/google-mail/gmail/v1/users/me/messageshttps://gateway.maton.ai/gmail/v1/users/me/messagesGenerated Mar 1, 2026
Automatically categorize and prioritize incoming customer support emails based on keywords and sender domains. Support agents can quickly filter unread messages from specific clients and apply labels for tracking response times. This reduces manual sorting and ensures urgent requests are addressed promptly.
Sales teams can monitor email outreach campaigns by tracking sent messages, responses, and follow-ups. Automatically star replies from prospects and apply labels for different campaign stages. This helps sales reps prioritize leads and maintain organized communication histories.
Team members working on projects can automatically label emails related to specific projects, clients, or deliverables. Create custom labels for different project phases and use query filters to quickly find relevant threads. This keeps project communications organized and accessible.
Individuals can implement GTD (Getting Things Done) or similar productivity systems by automatically labeling emails as actionable, reference, or waiting-for. Use query operators to filter unread starred messages and create drafts for responses that need careful composition.
Businesses can create automated systems that generate email reports by programmatically sending messages with attachments or summaries. Schedule regular status updates, sales reports, or monitoring alerts to be sent to stakeholders without manual intervention.
Build a subscription-based service that enhances Gmail functionality with advanced filtering, automation, and analytics. Offer tiered pricing based on features like automated labeling, response tracking, and team collaboration tools. Integrate with existing Gmail accounts through the API.
Create a service that syncs Gmail communications with CRM systems, automatically logging emails, tracking customer interactions, and updating contact records. Charge businesses based on the number of users or volume of emails processed. Offer custom integration setups for different CRM platforms.
Provide managed services for businesses to automate their email marketing campaigns, including personalized outreach, follow-up sequences, and performance tracking. Use the API to send, monitor, and analyze campaign emails while maintaining deliverability and compliance.
💬 Integration Tip
Start by testing with the list messages endpoint to understand the data structure, then implement connection management before building complex automation. Use the query operators extensively for efficient filtering.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
Read and send email via IMAP/SMTP. Check for new/unread messages, fetch content, search mailboxes, mark as read/unread, and send emails with attachments. Works with any IMAP/SMTP server including Gmail, Outlook, 163.com, vip.163.com, 126.com, vip.126.com, 188.com, and vip.188.com.
Automatically logs into email accounts (Gmail, Outlook, QQ Mail, etc.) and generates daily email summaries. Use when the user wants to get a summary of their emails, check important messages, or create daily email digests.
Fetch content from Feishu (Lark) Wiki, Docs, Sheets, and Bitable. Automatically resolves Wiki URLs to real entities and converts content to Markdown.
Manage Feishu (Lark) calendars by listing, searching, checking schedules, syncing events, and marking tasks with automated date extraction.
Set up Gmail API access via gog CLI with manual OAuth flow. Use when setting up Gmail integration, renewing expired OAuth tokens, or troubleshooting Gmail authentication on headless servers.