通过

列出 mailFolder

  • 项目

命名空间：microsoft.graph

重要

Microsoft Graph /beta 版本下的 API 可能会发生更改。 不支持在生产应用程序中使用这些 API。 若要确定 API 是否在 v1.0 中可用，请使用 版本 选择器。

直接在已登录用户的根文件夹下获取邮件文件夹集合。 返回的集合包括直接在根目录下的所有邮件搜索文件夹。

默认情况下，此操作不会返回隐藏文件夹。 使用查询参数 includeHiddenFolders 将它们包含在响应中。 此操作不会返回邮箱中的所有邮件文件夹，仅返回根文件夹的子文件夹。 若要返回邮箱中的所有邮件文件夹，必须 单独遍历每个子文件夹。

此 API 可用于以下国家级云部署。

全局服务 美国政府 L4 美国政府 L5 (DOD) 由世纪互联运营的中国
✅ ✅ ✅ ✅

权限

为此 API 选择标记为最低特权的权限。 只有在应用需要它时，才使用更高的特权权限。 有关委派权限和应用程序权限的详细信息，请参阅权限类型。 要了解有关这些权限的详细信息，请参阅 权限参考。

权限类型 最低特权权限 更高特权权限
委派（工作或学校帐户） Mail.ReadBasic Mail.ReadWrite、Mail.Read
委派（个人 Microsoft 帐户） Mail.ReadBasic Mail.ReadWrite、Mail.Read
应用程序 Mail.ReadBasic.All Mail.ReadWrite、Mail.Read

HTTP 请求

若要获取指定用户的邮箱中根文件夹中的所有邮件文件夹，请排除隐藏的文件夹：

GET /me/mailFolders
GET /users/{id | userPrincipalName}/mailFolders

若要在答复中包括隐藏的邮件文件夹，请执行以下操作：

GET /me/mailFolders/?includeHiddenFolders=true
GET /users/{id | userPrincipalName}/mailFolders/?includeHiddenFolders=true

可选的查询参数

若要返回所有 mailFolder 的列表（包括隐藏的项目，其 isHidden 属性为 true），则如 HTTP 请求 部分所示，在请求 URL 中，将 includeHiddenFolders 查询参数指定为 true。

此方法支持 OData 查询参数 ，以帮助自定义响应。

请求标头

标头 值
Authorization 持有者 {token}。 必填。 详细了解 身份验证和授权。

请求正文

请勿提供此方法的请求正文。

响应

如果成功，此方法在响应正文中返回 200 OK 响应代码和 mailFolder 对象集合。

示例

示例 1：列出已登录用户邮箱中的邮件文件夹

此示例在答复中包括了 mailSearchFolder 对象。 邮件搜索文件夹是收件箱下的子文件夹，显示名称为"每周摘要"。

请求

以下示例显示了一个请求。

GET https://graph.microsoft.com/beta/me/mailFolders

响应

下面是响应的示例，其中包括 一个 mailSearchFolder ，它是收件箱下的子文件夹。

注意：为了提高可读性，可能缩短了此处显示的响应对象。

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#users('68ca8ec0-11f8-456b-a785-70d9936650d5')/mailFolders",
    "value": [
        {
            "id": "AQMkADYAAAIBXQAAAA==",
            "displayName": "Archive",
            "parentFolderId": "AQMkADYAAAIBCAAAAA==",
            "childFolderCount": 0,
            "unreadItemCount": 0,
            "totalItemCount": 0,
            "wellKnownName": "archive",
            "isHidden": false
        },
        {
            "id": "AQMkADYAAAIBFQAAAA==",
            "displayName": "Conversation History",
            "parentFolderId": "AQMkADYAAAIBCAAAAA==",
            "childFolderCount": 1,
            "unreadItemCount": 0,
            "totalItemCount": 0,
            "wellKnownName": "conversationhistory",
            "isHidden": false
        },
        {
            "id": "AQMkADYAAAIBCgAAAA==",
            "displayName": "Deleted Items",
            "parentFolderId": "AQMkADYAAAIBCAAAAA==",
            "childFolderCount": 0,
            "unreadItemCount": 0,
            "totalItemCount": 0,
            "wellKnownName": "deleteditems",
            "isHidden": false
        },
        {
            "id": "AQMkADYAAAIBDwAAAA==",
            "displayName": "Drafts",
            "parentFolderId": "AQMkADYAAAIBCAAAAA==",
            "childFolderCount": 0,
            "unreadItemCount": 0,
            "totalItemCount": 0,
            "wellKnownName": "drafts",
            "isHidden": false
        },
        {
            "id": "AQMkADYAAAIBDAAAAA==",
            "displayName": "Inbox",
            "parentFolderId": "AQMkADYAAAIBCAAAAA==",
            "childFolderCount": 1,
            "unreadItemCount": 70,
            "totalItemCount": 71,
            "wellKnownName": "inbox",
            "isHidden": false
        },
        {
            "@odata.type": "#microsoft.graph.mailSearchFolder",
            "id": "AAMkADYRAAAZg1yTAAA=",
            "displayName": "Weekly digests",
            "parentFolderId": "AQMkADYAAAIBDAAAAA==",
            "childFolderCount": 0,
            "unreadItemCount": 4,
            "totalItemCount": 5,
            "wellKnownName": null,
            "isHidden": false,
            "isSupported": true,
            "filterQuery": "contains(subject, 'weekly digest')"
        },
        {
            "id": "AQMkADYAAAIBGQAAAA==",
            "displayName": "Junk Email",
            "parentFolderId": "AQMkADYAAAIBCAAAAA==",
            "childFolderCount": 0,
            "unreadItemCount": 0,
            "totalItemCount": 0,
            "wellKnownName": "junkemail",
            "isHidden": false
        },
        {
            "id": "AQMkADYAAAIBCwAAAA==",
            "displayName": "Outbox",
            "parentFolderId": "AQMkADYAAAIBCAAAAA==",
            "childFolderCount": 0,
            "unreadItemCount": 0,
            "totalItemCount": 0,
            "wellKnownName": "outbox",
            "isHidden": false
        },
        {
            "id": "AQMkADYAAAIBCQAAAA==",
            "displayName": "Sent Items",
            "parentFolderId": "AQMkADYAAAIBCAAAAA==",
            "childFolderCount": 0,
            "unreadItemCount": 0,
            "totalItemCount": 0,
            "wellKnownName": "sentitems",
            "isHidden": false
        }
    ]
}

提示

如果集合超过默认页面大小 (10 个项目) ，响应中将返回 @odata.nextLink 属性，以指示更多项可用，并为下一页项提供请求 URL。

可以通过可选的查询字符串参数控制页面大小

示例 2：包含已登录用户邮箱中的隐藏文件夹

此示例使用 includeHiddenFolders 查询参数获取邮件文件夹列表，包括隐藏邮件文件夹。 响应包括将 isHidden 设置为 true的“待筛选”文件夹。

请求

GET https://graph.microsoft.com/beta/me/mailFolders/?includeHiddenFolders=true

响应

以下示例显示了相应的响应。

注意： 为提高可读性，此处显示的答复对象已缩短，并且用户邮箱中不包含所有默认文件夹。

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#users('68ca8ec0-11f8-456b-a785-70d9936650d5')/mailFolders",
    "value": [
        {
            "id": "AAMkADg3NTY5MDg4LWMzYmQtNDQzNi05OTgwLWAAA=",
            "displayName": "Clutter",
            "parentFolderId": "AAMkADg3NTY5MDg4LWMzYmQtEIAAA=",
            "childFolderCount": 0,
            "unreadItemCount": 0,
            "totalItemCount": 0,
            "wellKnownName": null,
            "isHidden": true
        },
        {
            "id": "AAMkADg3NTY5MDg4LWMzYmQtNDQzNi05OTgwLWAAA=",
            "displayName": "Conversation History",
            "parentFolderId": "AAMkADg3NTY5MDg4LWMzYmQtEIAAA=",
            "childFolderCount": 1,
            "unreadItemCount": 0,
            "totalItemCount": 0,
            "wellKnownName": "conversationhistory",
            "isHidden": false
        }
    ]
}