Gmail To Calendar
Skill 初始化规则： 使用此 skill 前，需检查 skill 目录下是否存在 .env 文件保存 MATON_API_KEY。如果不存在，提示用户提供 API key 并创建 .env 文件后，再执行后续操作。
Access the Gmail API with managed OAuth authentication. Read, send, and manage emails, threads, labels, and drafts.
This skill also includes a bundled helper script, gmail_to_calendar.py, for a tested Gmail -> Google Calendar workflow. Use it when an email contains schedule details and you want to create a calendar event through the same Maton account.
.env 文件说明
API Key 保存在 skill 目录的 .env 文件中（不要提交到 Git）。首次使用前需要创建：
# 在 skill 目录下创建 .env 文件
echo "MATON_API_KEY=你的API密钥" > ~/.openclaw/workspace/skills/gmail-to-calendar/.env
所有 exec 调用会自动从该文件加载环境变量（通过 set -a; source ~/.openclaw/workspace/skills/gmail-to-calendar/.env; set +a）。
Quick Start
# 自动从 .env 加载环境变量后，列出邮件
set -a; source ~/.openclaw/workspace/skills/gmail-to-calendar/.env; set +a
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: API key 已保存在 skill 目录的 .env 文件中（见上方说明）。在 exec 调用中，通过以下方式加载：
set -a; source ~/.openclaw/workspace/skills/gmail-to-calendar/.env; set +a
Getting Your API Key
- Sign in or create an account at maton.ai
- Go to maton.ai/settings
- Copy your API key
- 将 API key 写入
~/.openclaw/workspace/skills/gmail-to-calendar/.env 文件（格式：MATON_API_KEY=你的密钥）
Connection Management
Manage your Google OAuth connections at https://ctrl.maton.ai.
List Connections
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
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
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:
{
"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
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:
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.
Gmail -> Google Calendar
This workflow requires both of the following Maton connections to be ACTIVE:
google-mailgoogle-calendar
Use the bundled helper script when the email body includes either structured event fields or recognizable free-text schedule details. The script:
- Reads a Gmail message by
--message-id or Gmail search --query
- Extracts event details from explicit fields first, then falls back to free-text parsing
- Creates an event in Google Calendar
Supported field labels in the email body:
- Summary:
Title, Summary, 标题, 主题
- Date:
Date, 日期
- Start time:
Start, Start Time, 开始, 开始时间
- End time:
End, End Time, 结束, 结束时间
- Time zone:
Time Zone, Timezone, 时区
- Location:
Location, 地点
- Description:
Description, Details, 描述, 详情
Recommended email format:
Title: Product Sync
Date: 2026-04-21
Start: 15:00
End: 15:30
Time Zone: Asia/Shanghai
Location: Zoom
Description: Weekly review with the product team.
Supported free-text patterns include:
- Absolute dates:
2026-04-25 15:00-16:00, 2026年4月25日下午3点到4点
- Relative dates:
tomorrow 3pm-4pm, 明天下午 3 点到 4 点
- Weekdays:
next Tuesday 2pm, 下周三上午10点
- Meeting locations:
on Google Meet, 在 Zoom, or a meeting URL such as https://meet.google.com/...
Example free-text email body:
我们约在2026年4月25日下午3点到4点，在 Zoom 讨论项目里程碑。
Another example:
Let's meet tomorrow 3pm-3:45pm on Google Meet to discuss the role.
The script loads MATON_API_KEY from the local .env file automatically.
Dry run without writing to Google Calendar:
python ~/.openclaw/workspace/skills/gmail-to-calendar/gmail_to_calendar.py \
--query 'subject:"面试安排" newer_than:7d' \
--dry-run
Keep the old strict behavior and disable free-text fallback:
python ~/.openclaw/workspace/skills/gmail-to-calendar/gmail_to_calendar.py \
--query 'subject:"面试安排" newer_than:7d' \
--structured-only
Create an event from a specific Gmail message:
python ~/.openclaw/workspace/skills/gmail-to-calendar/gmail_to_calendar.py \
--message-id 19da9b349a1016c8
Pin specific Maton connections if multiple Gmail or Google Calendar accounts are active:
python ~/.openclaw/workspace/skills/gmail-to-calendar/gmail_to_calendar.py \
--query 'subject:"[TEST] Maton Gmail->Calendar"' \
--mail-connection e7eb1207-4f81-43f8-8aaf-2a483b3b48b7 \
--calendar-connection a40e0d20-4f6d-4461-8db0-877ed581627e
The underlying calendar write uses the Google Calendar Maton gateway:
POST /google-calendar/calendar/v3/calendars/primary/events
API Reference
List Messages
GET /google-mail/gmail/v1/users/me/messages?maxResults=10
With query filter:
GET /google-mail/gmail/v1/users/me/messages?q=is:unread&maxResults=10
Get Message
GET /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=Date
Send Message
POST /google-mail/gmail/v1/users/me/messages/send
Content-Type: application/json
{
"raw": "BASE64_ENCODED_EMAIL"
}
List Labels
GET /google-mail/gmail/v1/users/me/labels
List Threads
GET /google-mail/gmail/v1/users/me/threads?maxResults=10
Get Thread
GET /google-mail/gmail/v1/users/me/threads/{threadId}
Modify Message Labels
POST /google-mail/gmail/v1/users/me/messages/{messageId}/modify
Content-Type: application/json
{
"addLabelIds": ["STARRED"],
"removeLabelIds": ["UNREAD"]
}
Trash Message
POST /google-mail/gmail/v1/users/me/messages/{messageId}/trash
Create Draft
POST /google-mail/gmail/v1/users/me/drafts
Content-Type: application/json
{
"message": {
"raw": "BASE64URL_ENCODED_EMAIL"
}
}
Send Draft
POST /google-mail/gmail/v1/users/me/drafts/send
Content-Type: application/json
{
"id": "{draftId}"
}
Get Profile
GET /google-mail/gmail/v1/users/me/profile
Query Operators
Use 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 attachments
Code Examples
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
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
- 检查
.env 文件是否存在且包含有效密钥：
cat ~/.openclaw/workspace/skills/gmail-to-calendar/.env
- Verify the API key is valid by listing connections:
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
