Exchange Online 管理员 API 中的邮箱终结点

注意

本文中所述的功能目前为预览版，并非在所有组织中都可用，并且可能会发生更改。

Exchange Online 管理员 API 中的邮箱终结点允许查看和管理代表代理发送。

典型用例包括：

列出邮箱或检索特定邮箱的详细信息。
检查 SendOnBehalfTo 的委托配置，包括委托的可选显示名称。
通过覆盖完整的委托列表或进行增量更改 (添加/删除) 来更新代表发送代理。

Exchange Online 管理员 API 提供了一种基于 REST 的方式来执行特定 PowerShell cmdlet，取代了旧版 Exchange Web Services (EWS) 方案。有关详细信息，请参阅 Exchange Online 管理员 API 概述。

端点 URL

POST https://outlook.office365.com/adminapi/v2.0/<TenantID>/Mailbox

提示

按照支持的环境和基 URL 中所述，使用环境的基 URL。

请求模型

标题

Authorization: Bearer <auth token>
Content-Type: application/json
X-AnchorMailbox: <routing hint>

有关 X-AnchorMailbox 值，请参阅 X-AnchorMailbox 路由提示。

正文

Get-Mailbox：

{
  "CmdletInput": {
    "CmdletName": "Get-Mailbox",
    "Parameters": {
      "Identity": "alex@contoso.com",                        //optional
      "ResultSize": <Integer | "Unlimited">,                 //optional (pagination)
      "IncludeGrantSendOnBehalfTowithDisplayNames": true     //optional
    }
  }
}

Set-Mailbox (覆盖委托) ：

{
  "CmdletInput": {
    "CmdletName": "Set-Mailbox",
    "Parameters": {
      "Identity": "alex@contoso.com",      //required
      "GrantSendOnBehalfTo": [             //required
        "delegate1@contoso.com",
        "delegate2@contoso.com"
      ]
    }
  }
}

Set-Mailbox () 添加/删除委托 ：

{
  "CmdletInput": {
    "CmdletName": "Set-Mailbox",
    "Parameters": {
      "Identity": "alex@contoso.com",                //required
      "GrantSendOnBehalfTo": {                       //required
        "add": ["delegate3@contoso.com"],
        "remove": ["delegate1@contoso.com"],
        "@odata.type": "#Exchange.GenericHashTable"
      }
    }
  }
}

分页

Get-Mailbox cmdlet 上的 ResultSize 参数控制分页。默认情况下，最多返回 1,000 个结果。

如果有更多结果可用，则响应将包含具有 @odata.nextLink 延续 URL 的属性。若要提取下一页，请使用同一正文向中的 @odata.nextLink URL 发出新的 POST 请求。

属性选择

此终结点支持 $select 查询参数在响应中仅返回特定属性。

支持的 cmdlet 和参数

以下列表介绍了此终结点支持的 cmdlet 和参数。此终结点正文中的其他 cmdlet 会导致错误。

Get-Mailbox：

只有下表中所述的 Get-Mailbox 参数可通过 REST 终结点使用：

参数	必需	类型	说明
Identity	可选	String	指定要检索相关信息的邮箱。有效值为 name、可分辨名称、别名、用户主体名称 (UPN) 、GUID 或其他唯一标识符。如果省略并受 ResultSize 约束，则 cmdlet 将返回所有邮箱。
ResultSize	可选	整数或无限制	限制返回的结果数。有效值是整数 (例如，10) 或值 `"Unlimited"`。
IncludeGrantSendOnBehalfToWithDisplayNames	可选	布尔值	该值 `True` 包括 SendOnBehalfTo 委托条目及其显示名称。注意：此参数正在分阶段推出，可能并非在所有组织中都可用。

Set-Mailbox：

只有下表中所述的 Set-Mailbox 参数可通过 REST 终结点使用：

参数	必需	类型	说明
Identity	可选	String	指定目标邮箱。有效值为 name、可分辨名称、别名、UPN、GUID 或其他唯一标识符。
GrantSendOnBehalfTo	必需	集合或哈希表	覆盖：完整委托列表的 SMTP 地址列表。例如，`["bob@contoso.com","carol@contoso.com"]`。添加/删除：包含 `add` 和/或 `remove` 数组的哈希表，以修改委托列表。例如，`{ "add" : ["dave@contoso.com"], remove : ["carol@contoso.com"] }`。

响应概述

注意

在预览期间，终结点在 API 响应中包含完整的 Get-Mailbox cmdlet 输出。在过渡到公共版本期间，响应将仅限于本节中列出的核心属性， (EWS 等效方案) 所需的属性。建议仅使用本节中列出的属性。我们将记录对可用属性所做的任何更改。

Get-Mailbox 响应是 JSON 对象或具有邮箱属性的列表数组。将返回下列属性：
- 标识：邮箱的规范标识符通常 (别名或可分辨名称) 。
- ID：邮箱对象的服务标识符。
- 名称：邮箱的唯一 Exchange 显示名称。
- DisplayName：用户友好的显示名称。
- UserPrincipalName：与邮箱关联的帐户。
- 别名：唯一邮箱别名。
- ExternalDirectoryObjectId：Microsoft Entra ID邮箱的对象 GUID。
- RecipientType：有关可能的邮箱值，请参阅 RecipientType。
- RecipientTypeDetails：有关可能的邮箱值，请参阅 RecipientTypeDetails。
- EmailAddresses：收件人的所有代理地址 (包括 SMTP：和 smtp：条目) 。
- PrimarySmtpAddress：收件人 (的主要 SMTP 地址对应于 EmailAddresses) 中的 SMTP：值。
- MaxSendSize：邮箱可以发送的最大邮件大小。
- GrantSendOnBehalfTo： (SMTP 地址的代理人列表，) 授予邮箱的“代表发送”权限。
- GrantSendOnBehalfToWithDisplayNames：请求) 时 (具有委托显示名称的相同列表。
Set-Mailbox cmdlet 在成功后返回HTTP 200 OK。成功更新不需要响应正文。

示例

示例 1：简单 Get-Mailbox (分页列表) ：

此示例列出了组织中的前 10 个邮箱。使用 @odata.nextLink 继续。

POST /adminapi/v2.0/<TenantID>/Mailbox HTTP/1.1
Host: outlook.office365.com
Authorization: Bearer <auth token>
Content-Type: application/json
X-AnchorMailbox: <Routing Hint>

{
  "CmdletInput": {
    "CmdletName": "Get-Mailbox",
    "Parameters": {
      "ResultSize": 10
    }
  }
}

示例 2：为特定邮箱 Get-Mailbox，并包含委托显示名称：

此示例返回具有显示名称的邮箱详细信息和 SendOnBehalfTo 委托。

POST /adminapi/v2.0/<TenantID>/Mailbox HTTP/1.1
Host: outlook.office365.com
Authorization: Bearer <auth token>
Content-Type: application/json
X-AnchorMailbox: <Routing Hint>

{
  "CmdletInput": {
    "CmdletName": "Get-Mailbox",
    "Parameters": {
      "Identity": "alex@contoso.com",
      "IncludeGrantSendOnBehalfTowithDisplayNames": true
    }
  }
}

示例 3：Set-Mailbox：覆盖委托列表：

此示例使用指定的委托覆盖指定邮箱上的 SendOnBehalfTo 列表。

结果是： 200 正常。 delegate1@contoso.com 并 delegate2@contoso.com 替换邮箱上的任何/所有现有 SendOnBehalfTo 委托。

POST /adminapi/v2.0/<TenantID>/Mailbox HTTP/1.1
Host: outlook.office365.com
Authorization: Bearer <auth token>
Content-Type: application/json
X-AnchorMailbox: <Routing Hint>

{
  "CmdletInput": {
    "CmdletName": "Set-Mailbox",
    "Parameters": {
      "Identity": "alex@contoso.com",
      "GrantSendOnBehalfTo@odata.type": "#Collection(String)",
      "GrantSendOnBehalfTo": [
        "delegate1@contoso.com",
        "delegate2@contoso.com"
      ]
    }
  }
}

示例 4：Set-Mailbox：将委托添加到现有委托列表：

本示例将新的 SendOnBehalfTo 委托添加到指定邮箱，同时保留现有委托。

结果是： 200 正常。 delegate3@contoso.com 和 delegate4@contoso.com 将添加到邮箱上的现有代理人列表。

POST /adminapi/v2.0/<TenantID>/Mailbox HTTP/1.1
Host: outlook.office365.com
Authorization: Bearer <auth token>
Content-Type: application/json
X-AnchorMailbox: <Routing Hint>

{
  "CmdletInput": {
    "CmdletName": "Set-Mailbox",
    "Parameters": {
      "Identity": "alex@contoso.com",
      "GrantSendOnBehalfTo": {
        "add": [
          "delegate3@contoso.com",
          "delegate4@contoso.com"
        ],
        "@odata.type": "#Exchange.GenericHashTable"
      }
    }
  }
}

Last updated on 2025-11-17

通过