Outlook: 用于 AI 智能体的 Microsoft Graph API 集成 - Openclaw Skills

什么是 Outlook？

Outlook 技能提供了一个通向 Microsoft Graph API 的专门网关，使开发者能够构建直接与 Microsoft 365 交互的 AI 驱动工作流。通过利用像这样的 Openclaw Skills，您可以绕过手动 OAuth 令牌管理的复杂性。该服务处理身份验证握手和令牌刷新，为您的智能体提供一个稳定的端点来读取、发送和组织通信。

对于希望将专业通信套件集成到其智能体工作流中的开发者来说，这项技能至关重要。无论您是管理大量电子邮件还是自动化复杂的调度任务，此集成都能确保您的 Openclaw Skills 专注于逻辑而非基础设施维护。

下载入口:https://github.com/openclaw/skills/tree/main/skills/byungkyu/outlook-api

安装与下载

1. ClawHub CLI

从源直接安装技能的最快方式。

npx clawhub@latest install outlook-api

2. 手动安装

将技能文件夹复制到以下位置之一

全局模式 ~/.openclaw/skills/ 工作区 <project>/skills/

优先级：工作区 > 本地 > 内置

3. 提示词安装

将此提示词复制到 OpenClaw 即可自动安装。

请帮我使用 Clawhub 安装 outlook-api。如果尚未安装 Clawhub，请先安装（npm i -g clawhub）。

Outlook 应用场景

• 根据优先级或内容自动对收到的电子邮件进行分类和分选。
• 直接从 AI 智能体创建并发送个性化的电子邮件草稿或回复。
• 通过自动化的参会者管理来安排、更新和取消日历事件及会议。
• 通过编程方式创建、更新或删除条目来管理专业联系人列表。
• 同步邮件文件夹结构以组织历史数据并归档通信。

Outlook 工作原理

1. 开发者配置 Maton API 密钥，并通过控制平面建立连接以授权 Outlook 帐户。
2. 系统管理与 Microsoft 的 OAuth 流程，生成安全的会话令牌。
3. AI 智能体向网关 URL 发送标准 REST 请求，指定所需的 Microsoft Graph 路径。
4. 网关拦截请求，注入有效的 OAuth 持有者令牌，并将调用代理到 Microsoft 的服务器。
5. 智能体接收结构化的 JSON 响应，使其能够在 Openclaw Skills 生态系统中执行进一步的操作或数据分析。

Outlook 配置指南

要使用 Openclaw Skills 将此功能集成到您的项目中，请按照以下配置步骤操作：

1. 从 Maton 设置页面 获取您的 API 密钥。
2. 将您的密钥导出为环境变量：

export MATON_API_KEY="YOUR_API_KEY"

3. 为 Outlook 初始化一个新连接：

curl -X POST https://ctrl.maton.ai/connections r
  -H "Authorization: Bearer $MATON_API_KEY" r
  -H "Content-Type: application/json" r
  -d '{"app": "outlook"}'

4. 导航到响应中提供的 url，在浏览器中完成 Microsoft OAuth 授权。

Outlook 数据架构与分类体系

该技能利用原生 Microsoft Graph 模式，通过网关映射请求。关键数据实体包括：

实体	端点路径	描述
消息	/v1.0/me/messages	核心电子邮件对象，包括主题、正文（HTML/文本）和元数据。
文件夹	/v1.0/me/mailFolders	组织单元，如收件箱、草稿箱和自定义文件夹。
事件	/v1.0/me/calendar/events	包含时间、地点和参会者数据的日历项。
联系人	/v1.0/me/contacts	用户联系信息，包括电子邮件地址和姓名。
用户	/v1.0/me	认证帐户的个人资料信息。

所有端点都支持 OData 查询参数（$filter、$top、$select、$orderby），以便在 Openclaw Skills 中进行高级数据操作。

name: outlook
description: |
  Microsoft Outlook API integration with managed OAuth. Read, send, and manage emails, folders, calendar events, and contacts via Microsoft Graph. Use this skill when users want to interact with Outlook. For other third party apps, use the api-gateway skill (https://clawhub.ai/byungkyu/api-gateway).
compatibility: Requires network access and valid Maton API key
metadata:
  author: maton
  version: "1.0"
  clawdbot:
    emoji: ??
    requires:
      env:
        - MATON_API_KEY

Outlook

Access the Microsoft Outlook API (via Microsoft Graph) with managed OAuth authentication. Read, send, and manage emails, folders, calendar events, and contacts.

Quick Start

# Get user profile
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

Base URL

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

Replace {native-api-path} with the actual Microsoft Graph API endpoint path. The gateway proxies requests to graph.microsoft.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:

export MATON_API_KEY="YOUR_API_KEY"

Getting Your API Key

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

Connection Management

Manage your Microsoft 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=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

Create Connection

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

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": "outlook",
    "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 Outlook 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/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

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

API Reference

User Profile

GET /outlook/v1.0/me

Mail Folders

List Mail Folders

GET /outlook/v1.0/me/mailFolders

Get Mail Folder

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

Well-known folder names: Inbox, Drafts, SentItems, DeletedItems, Archive, JunkEmail

Create Mail Folder

POST /outlook/v1.0/me/mailFolders
Content-Type: application/json

{
  "displayName": "My Folder"
}

Delete Mail Folder

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

List Child Folders

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

Messages

List Messages

GET /outlook/v1.0/me/messages

From specific folder:

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

With query filter:

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

Get Message

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

Create Draft

POST /outlook/v1.0/me/messages
Content-Type: application/json

{
  "subject": "Hello",
  "body": {
    "contentType": "Text",
    "content": "This is the email body."
  },
  "toRecipients": [
    {
      "emailAddress": {
        "address": "[email protected]"
      }
    }
  ]
}

Send Message

POST /outlook/v1.0/me/sendMail
Content-Type: application/json

{
  "message": {
    "subject": "Hello",
    "body": {
      "contentType": "Text",
      "content": "This is the email body."
    },
    "toRecipients": [
      {
        "emailAddress": {
          "address": "[email protected]"
        }
      }
    ]
  },
  "saveToSentItems": true
}

Send Existing Draft

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

Update Message

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

{
  "isRead": true
}

Delete Message

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

Move Message

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

{
  "destinationId": "{folderId}"
}

Calendar

List Calendars

GET /outlook/v1.0/me/calendars

List Events

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

With date filter:

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

Get Event

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

Create Event

POST /outlook/v1.0/me/calendar/events
Content-Type: application/json

{
  "subject": "Meeting",
  "start": {
    "dateTime": "2024-01-15T10:00:00",
    "timeZone": "UTC"
  },
  "end": {
    "dateTime": "2024-01-15T11:00:00",
    "timeZone": "UTC"
  },
  "attendees": [
    {
      "emailAddress": {
        "address": "[email protected]"
      },
      "type": "required"
    }
  ]
}

Delete Event

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

Contacts

List Contacts

GET /outlook/v1.0/me/contacts

Get Contact

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

Create Contact

POST /outlook/v1.0/me/contacts
Content-Type: application/json

{
  "givenName": "John",
  "surname": "Doe",
  "emailAddresses": [
    {
      "address": "[email protected]"
    }
  ]
}

Delete Contact

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

Query Parameters

Use OData query parameters:

• $top=10 - Limit results
• $skip=20 - Skip results (pagination)
• $select=subject,from - Select specific fields
• $filter=isRead eq false - Filter results
• $orderby=receivedDateTime desc - Sort results
• $search="keyword" - Search content

Code Examples

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'}
)

Notes

• Use me as the user identifier for the authenticated user
• Message body content types: Text or HTML
• Well-known folder names work as folder IDs: Inbox, Drafts, SentItems, etc.
• Calendar events use ISO 8601 datetime format
• 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

Troubleshooting: API Key Issues

1. Check that the MATON_API_KEY environment variable is set:

echo $MATON_API_KEY

2. 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

1. Ensure your URL path starts with outlook. For example:

• Correct: https://gateway.maton.ai/outlook/v1.0/me/messages
• Incorrect: https://gateway.maton.ai/v1.0/me/messages

Resources

• Microsoft Graph API Overview
• Mail API
• Calendar API
• Contacts API
• Query Parameters
• Maton Community
• Maton Support