OpenClaw Skills Outlook API 技能使用参考手册

概述

Outlook API 是用于让 OpenClaw 通过 Microsoft Graph API 与 Microsoft Outlook 平台交互的 OpenClaw 技能，该技能通过 Maton 平台的网关进行 OAuth 认证管理，无需手动处理复杂的 OAuth 流程，支持邮件的读取、发送、管理，以及文件夹、日历事件、联系人的管理，适合需要在 AI 助手中集成 Outlook 功能的场景，例如邮件内容搜索、邮件自动回复、日历事件管理、联系人管理等。

技能信息

• 名称：outlook-api
• 描述：通过 Microsoft Graph API 与 Microsoft Outlook 平台交互，支持邮件、文件夹、日历事件和联系人的管理，使用 Maton 平台的网关进行 OAuth 认证管理，无需手动处理复杂的 OAuth 流程。
• 版本：1.0.3
• 作者：maton
• 主页：https://maton.ai
• 依赖：
  • 需要网络访问权限
  • 需要有效的 Maton API Key（MATON_API_KEY）
• 触发词："Outlook 邮件管理"、"Outlook 日历管理"、"Outlook 联系人管理"、"Outlook 文件夹管理"、"Outlook 邮件发送"

👤 作者：byungkyu
🦞 官方地址：https://clawhub.ai/byungkyu/outlook-api
👉 Skills 下载地址：outlook-api-1.0.3.zip

快速开始

获取用户资料

## 获取用户资料
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/outlook/v1.0/me')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

基础 URL

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

将{native-api-path}替换为实际的 Microsoft Graph API 端点路径。网关会将请求代理到graph.microsoft.com，并自动注入你的 OAuth 令牌。

认证

所有请求都需要在 Authorization 头中包含 Maton API 密钥：

Authorization: Bearer $MATON_API_KEY

环境变量：将你的 API 密钥设置为MATON_API_KEY环境变量：

export MATON_API_KEY="你的 API 密钥"

获取 API 密钥

1. 访问maton.ai注册或登录账户
2. 进入maton.ai/settings页面
3. 复制你的 API 密钥

连接管理

你可以在https://ctrl.maton.ai管理你的 Microsoft OAuth 连接。

列出连接

## 列出连接
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections?app=outlook&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

创建连接

## 创建连接
python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'outlook'}).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

获取连接

## 获取连接
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

响应：

{
"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": "outlook",
"metadata": {}
}
}

在浏览器中打开返回的url以完成 OAuth 授权。

删除连接

## 删除连接
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

指定连接

如果你有多个 Outlook 连接，可以通过Maton-Connection头指定使用哪个连接：

## 指定连接
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/outlook/v1.0/me')
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

如果省略，网关将使用默认（最早的）活动连接。

API 参考

用户资料

GET /outlook/v1.0/me

邮件文件夹

列出邮件文件夹

GET /outlook/v1.0/me/mailFolders

获取邮件文件夹

GET /outlook/v1.0/me/mailFolders/{folderId}

知名文件夹名称：Inbox（收件箱）、Drafts（草稿箱）、SentItems（已发送邮件）、DeletedItems（已删除邮件）、Archive（存档）、JunkEmail（垃圾邮件）

创建邮件文件夹

POST /outlook/v1.0/me/mailFolders
Content-Type: application/json
{
"displayName": "我的文件夹"
}

删除邮件文件夹

DELETE /outlook/v1.0/me/mailFolders/{folderId}

列出子文件夹

GET /outlook/v1.0/me/mailFolders/{folderId}/childFolders

邮件消息

列出邮件消息

GET /outlook/v1.0/me/messages

从指定文件夹列出：

GET /outlook/v1.0/me/mailFolders/Inbox/messages

带查询过滤器：

GET /outlook/v1.0/me/messages?$filter=isRead eq false&$top=10

获取邮件消息

GET /outlook/v1.0/me/messages/{messageId}

创建草稿

POST /outlook/v1.0/me/messages
Content-Type: application/json
{
"subject": "你好",
"body": {
"contentType": "Text",
"content": "这是邮件正文。"
},
"toRecipients": [
{
"emailAddress": {
"address": "recipient@example.com"
}
}
]
}

发送邮件

POST /outlook/v1.0/me/sendMail
Content-Type: application/json
{
"message": {
"subject": "你好",
"body": {
"contentType": "Text",
"content": "这是邮件正文。"
},
"toRecipients": [
{
"emailAddress": {
"address": "recipient@example.com"
}
}
]
},
"saveToSentItems": true
}

发送现有草稿

POST /outlook/v1.0/me/messages/{messageId}/send

更新邮件消息

PATCH /outlook/v1.0/me/messages/{messageId}
Content-Type: application/json
{
"isRead": true
}

删除邮件消息

DELETE /outlook/v1.0/me/messages/{messageId}

移动邮件消息

POST /outlook/v1.0/me/messages/{messageId}/move
Content-Type: application/json
{
"destinationId": "{folderId}"
}

日历

列出日历

GET /outlook/v1.0/me/calendars

列出日历事件

GET /outlook/v1.0/me/calendar/events

带日期过滤器：

GET /outlook/v1.0/me/calendar/events?$filter=start/dateTime ge '2024-01-01'&$top=10

获取日历事件

GET /outlook/v1.0/me/events/{eventId}

创建日历事件

POST /outlook/v1.0/me/calendar/events
Content-Type: application/json
{
"subject": "会议",
"start": {
"dateTime": "2024-01-15T10:00:00",
"timeZone": "UTC"
},
"end": {
"dateTime": "2024-01-15T11:00:00",
"timeZone": "UTC"
},
"attendees": [
{
"emailAddress": {
"address": "attendee@example.com"
},
"type": "required"
}
]
}

删除日历事件

DELETE /outlook/v1.0/me/events/{eventId}

联系人

列出联系人

GET /outlook/v1.0/me/contacts

获取联系人

GET /outlook/v1.0/me/contacts/{contactId}

创建联系人

POST /outlook/v1.0/me/contacts
Content-Type: application/json
{
"givenName": "约翰",
"surname": " Doe",
"emailAddresses": [
{
"address": "john.doe@example.com"
}
]
}

删除联系人

DELETE /outlook/v1.0/me/contacts/{contactId}

查询参数

使用 OData 查询参数：

• $top=10 - 限制结果数量
• $skip=20 - 跳过结果（分页）
• $select=subject,from - 选择特定字段
• $filter=isRead eq false - 过滤结果
• $orderby=receivedDateTime desc - 对结果排序
• $search="keyword" - 搜索内容

代码示例

JavaScript

const response = await fetch(
'https://gateway.maton.ai/outlook/v1.0/me/messages?$top=10',
{
headers: {
'Authorization': `Bearer ${process.env.MATON_API_KEY}`
}
}
);

Python

import os
import requests
response = requests.get(
'https://gateway.maton.ai/outlook/v1.0/me/messages',
headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'},
params={'$top': 10, '$filter': 'isRead eq false'}
)

注意事项

1. 对于已认证的用户，使用me作为用户标识符
2. 邮件正文内容类型：Text（纯文本）或HTML（富文本）
3. 知名文件夹名称可以作为文件夹 ID 使用：Inbox、Drafts、SentItems等
4. 日历事件使用 ISO 8601 日期时间格式
5. 重要提示：使用 curl 命令时，如果 URL 包含括号（fields[]、sort[]、records[]），请使用curl -g以禁用 glob 解析
6. 重要提示：当将 curl 输出通过管道传递给jq或其他命令时，在某些 shell 环境中，$MATON_API_KEY等环境变量可能无法正确展开，可能会出现 "无效 API 密钥" 错误

错误处理

故障排除：API 密钥问题

1. 检查MATON_API_KEY环境变量是否已设置：

echo $MATON_API_KEY

1. 通过列出连接验证 API 密钥是否有效：

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

故障排除：无效应用名称

1. 确保你的 URL 路径以outlook开头。例如：

• 正确：https://gateway.maton.ai/outlook/v1.0/me/messages
• 错误：https://gateway.maton.ai/v1.0/me/messages

资源链接

• Microsoft Graph API 概述
• 邮件 API
• 日历 API
• 联系人 API
• 查询参数
• Maton 社区
• Maton 支持

许可证信息

该技能采用 MIT License，完整的许可条款如下：

The MIT License (MIT)
Copyright (c) 2026 Maton
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

元数据信息

该技能的元数据信息如下：

{
"ownerId": "kn75240wq8bnv2qm2xgry748jd80b9r0",
"slug": "outlook-api",
"version": "1.0.3",
"publishedAt": 1770756175470
}