m365

通过 CLI for Microsoft 365 使用 Microsoft 365

此技能使用 m365 CLI（CLI for Microsoft 365），通过 Microsoft Graph API 与 Outlook 邮件和日历交互。它支持跨平台运行（macOS、Linux、Windows）。

连接检查

开始任何操作前，并行运行以下两条命令：

m365 status --output json
m365 connection list --output json

如果当前连接的 "authType": "secret"，即可继续执行任务。

如果当前连接使用其他身份验证类型（例如 deviceCode），请通过 connection list 检查是否有处于非活动状态且 "authType": "secret" 的连接。如果有，请将其激活：

m365 connection use --name "<connection-name>"

只有在完全不存在 secret 连接时，才读取 ./setup.md（相对于此文件的路径）并按照其中的设置步骤操作。

所有面向用户邮箱的命令都需要 --userName <upn>（内置命令），或在 Graph API URL 中指定用户主体名称。如果不知道用户的 UPN（例如 [email protected]），请向用户询问。

重要说明

• 执行任何写入操作（发送邮件、创建/删除事件）前，务必先征得用户确认。
• CLI 内置了邮件命令，但不支持日历事件命令。日历操作请使用带 Graph API URL 的 m365 request。
• 使用 --output json 获取机器可读的输出。使用 --query（JMESPath）筛选字段。
• 每条命令都支持 -h / --help。使用 m365 <command group> --help 查看可用命令。

邮件

列出邮件

m365 outlook message list --folderName inbox --userName <upn> --output json

# With date range (endTime must be in the past)
m365 outlook message list --folderName inbox --userName <upn> \
  --startTime "2026-02-01T00:00:00Z" --endTime "2026-02-15T00:00:00Z" --output json

# Compact output with JMESPath
m365 outlook message list --folderName inbox --userName <upn> --output json \
  --query "[].{subject:subject,from:from.emailAddress.address,received:receivedDateTime,isRead:isRead}"

文件夹名称：inbox、drafts、sentitems、deleteditems、junkemail、archive。你也可以使用 --folderId。

读取指定邮件

m365 outlook message get --id <message-id> --userName <upn> --output json

搜索邮件（通过 Graph API）

内置的 message list 不支持搜索。请使用带 $search 或 $filter 的 m365 request：

# Full-text search (subject, body, sender, etc.)
m365 request --url "https://graph.microsoft.com/v1.0/users/<upn>/messages?\$search=%22keyword%22&\$select=subject,from,receivedDateTime&\$top=10" --method get --output json

# Filter by sender
m365 request --url "https://graph.microsoft.com/v1.0/users/<upn>/messages?\$filter=from/emailAddress/address eq '[email protected]'&\$select=subject,receivedDateTime&\$top=10" --method get --output json

注意：$search 和 $orderby 不能组合使用。$search 返回的结果按相关性排序。

列出邮件文件夹

m365 request --url "https://graph.microsoft.com/v1.0/users/<upn>/mailFolders?\$select=displayName,id,totalItemCount,unreadItemCount" --method get --output json

发送邮件

# Plain text
m365 outlook mail send --subject "Subject" --to "[email protected]" \
  --sender "<upn>" --bodyContents "Message body" --output json

# HTML with multiple recipients
m365 outlook mail send --subject "Subject" --to "[email protected],[email protected]" \
  --cc "[email protected]" --sender "<upn>" \
  --bodyContents "<p>HTML body</p>" --bodyContentType HTML --output json

# With attachment (max 3 MB per attachment)
m365 outlook mail send --subject "Subject" --to "[email protected]" \
  --sender "<upn>" --bodyContents "See attached." \
  --attachment "/path/to/file.pdf" --output json

# Send from shared mailbox
m365 outlook mail send --subject "Subject" --to "[email protected]" \
  --mailbox "[email protected]" --sender "<upn>" \
  --bodyContents "Sent from shared mailbox" --output json

回复邮件（通过 Graph API）

CLI 没有内置的回复命令。请使用带 Graph API 回复端点的 m365 request：

# Reply to sender only (plain text comment)
cat > /tmp/m365_reply.json << 'EOF'
{
  "comment": "Thanks, that works for me!"
}
EOF

m365 request --url "https://graph.microsoft.com/v1.0/users/<upn>/messages/<message-id>/reply" \
  --method post --body @/tmp/m365_reply.json --content-type "application/json"

# Reply all
m365 request --url "https://graph.microsoft.com/v1.0/users/<upn>/messages/<message-id>/replyAll" \
  --method post --body @/tmp/m365_reply.json --content-type "application/json"

# Reply with HTML body and additional recipients
cat > /tmp/m365_reply.json << 'EOF'
{
  "message": {
    "toRecipients": [
      {"emailAddress": {"address": "[email protected]", "name": "Extra Recipient"}}
    ]
  },
  "comment": "<p>Replying with <b>HTML</b> content.</p>"
}
EOF

m365 request --url "https://graph.microsoft.com/v1.0/users/<upn>/messages/<message-id>/reply" \
  --method post --body @/tmp/m365_reply.json --content-type "application/json"

Graph API 会自动处理邮件串联、引用原始邮件以及设置收件人。使用 comment 指定回复内容。也可以选择添加 message 对象，以添加或覆盖收件人。成功时返回 202 Accepted，且不带响应正文。需要 Mail.Send 权限。

移动 / 归档邮件

m365 outlook message move --id <message-id> \
  --sourceFolderName inbox --targetFolderName archive --output json

日历

日历操作使用带 Microsoft Graph API 端点的 m365 request。对于 POST/PUT/PATCH 请求，请将 JSON 正文写入临时文件，并通过 --body @/path/to/file.json --content-type "application/json" 传入。

列出日历

m365 request --url "https://graph.microsoft.com/v1.0/users/<upn>/calendars?\$select=name,id,canEdit,isDefaultCalendar" --method get --output json

列出即将发生的事件（日历视图）

在日期范围内查看事件时使用 calendarView（会展开重复事件）：

m365 request --url "https://graph.microsoft.com/v1.0/users/<upn>/calendarView?\$select=subject,start,end,location,organizer,isAllDay&startDateTime=2026-02-17T00:00:00Z&endDateTime=2026-02-24T00:00:00Z&\$orderby=start/dateTime" --method get --output json

获取事件详情（含与会者）

m365 request --url "https://graph.microsoft.com/v1.0/users/<upn>/events/<event-id>?\$select=subject,start,end,location,organizer,attendees,body,onlineMeeting" --method get --output json

搜索事件

m365 request --url "https://graph.microsoft.com/v1.0/users/<upn>/events?\$filter=contains(subject,'keyword')&\$select=subject,start,end&\$top=10" --method get --output json

创建事件

将事件 JSON 写入临时文件，然后执行 POST：

cat > /tmp/m365_event.json << 'EOF'
{
  "subject": "Meeting Title",
  "start": {"dateTime": "2026-03-01T14:00:00", "timeZone": "Europe/Berlin"},
  "end": {"dateTime": "2026-03-01T15:00:00", "timeZone": "Europe/Berlin"},
  "location": {"displayName": "Conference Room"},
  "attendees": [
    {"emailAddress": {"address": "[email protected]", "name": "Name"}, "type": "required"}
  ],
  "body": {"contentType": "text", "content": "Agenda: ..."}
}
EOF

m365 request --url "https://graph.microsoft.com/v1.0/users/<upn>/events" \
  --method post --body @/tmp/m365_event.json --content-type "application/json" --output json

删除事件

m365 request --url "https://graph.microsoft.com/v1.0/users/<upn>/events/<event-id>" \
  --method delete

提示

• 分页结果包含 @odata.nextLink。将该 URL 传给 m365 request，即可获取下一页。
• 使用 --query（JMESPath）提取指定字段：--query "[].{subject:subject,from:from.emailAddress.address}"。
• 对于 Graph API 请求，在 shell 中使用 \$ 转义 $。
• $top 用于限制结果数量：$top=5 最多返回 5 项。
• Graph API 的日期时间使用 UTC。设置事件的开始/结束时间时，使用 timeZone 指定本地时区。