Outlook

通过托管的 OAuth 认证访问 Microsoft Outlook API（经由 Microsoft Graph）。读取、发送和管理邮件、文件夹、日历事件以及联系人。

快速开始

# 获取用户资料
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="YOUR_API_KEY"

获取您的 API 密钥

1. 登录或前往maton.ai
2. 前往maton.ai/settings
3. 复制您的 API 密钥

连接管理

在以下地址管理您的 Microsoft OAuth 连接：https://ctrl.maton.ai。

列出连接

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-Connectionheader:

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}

已知文件夹名称：收件箱,草稿,已发送邮件,已删除邮件,存档,垃圾邮件

创建邮件文件夹

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": "John",
  "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'}
)

备注

• 使用我作为已验证用户的标识符
• 消息正文内容类型：文本或HTML
• 已知文件夹名称可作为文件夹ID使用：收件箱、草稿、已发送邮件等。
• 日历事件使用ISO 8601日期时间格式
• 重要提示：使用curl命令时，若URL包含方括号（字段[]、排序[]、记录[]），请使用curl -g) 用于禁用通配符解析
• 重要提示：当将 curl 输出通过管道传输到jq或其他命令时，在某些 shell 环境中，像$MATON_API_KEY这样的环境变量可能无法正确展开。通过管道传输时，您可能会收到"无效的 API 密钥"错误。

错误处理

故障排除：API 密钥问题

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

echo $MATON_API_KEY

2. 通过列出连接来验证 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 支持