列出 mailFolder

项目
02/01/2024

命名空间：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


// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Me.MailFolders.GetAsync();

重要

Microsoft Graph SDK 默认使用 v1.0 版本的 API，并且不支持 beta 版本中提供的所有类型、属性和 API。有关使用 SDK 访问 beta API 的详细信息，请参阅将 Microsoft Graph SDK 与 beta API 配合使用。

有关如何将 SDK 添加到项目并创建 authProvider 实例的详细信息，请参阅 SDK 文档。


// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc-beta users mail-folders list --user-id {user-id}

重要

有关如何将 SDK 添加到项目并创建 authProvider 实例的详细信息，请参阅 SDK 文档。



import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
	  //other-imports
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)



mailFolders, err := graphClient.Me().MailFolders().Get(context.Background(), nil)

重要

有关如何将 SDK 添加到项目并创建 authProvider 实例的详细信息，请参阅 SDK 文档。


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

MailFolderCollectionResponse result = graphClient.me().mailFolders().get();

重要

有关如何将 SDK 添加到项目并创建 authProvider 实例的详细信息，请参阅 SDK 文档。


const options = {
	authProvider,
};

const client = Client.init(options);

let mailFolders = await client.api('/me/mailFolders')
	.version('beta')
	.get();

重要

有关如何将 SDK 添加到项目并创建 authProvider 实例的详细信息，请参阅 SDK 文档。


<?php
use Microsoft\Graph\GraphServiceClient;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);


$result = $graphServiceClient->me()->mailFolders()->get()->wait();

重要

有关如何将 SDK 添加到项目并创建 authProvider 实例的详细信息，请参阅 SDK 文档。


Import-Module Microsoft.Graph.Beta.Mail

# A UPN can also be used as -UserId.
Get-MgBetaUserMailFolder -UserId $userId

重要

有关如何将 SDK 添加到项目并创建 authProvider 实例的详细信息，请参阅 SDK 文档。


from msgraph import GraphServiceClient

graph_client = GraphServiceClient(credentials, scopes)


result = await graph_client.me.mail_folders.get()

重要

有关如何将 SDK 添加到项目并创建 authProvider 实例的详细信息，请参阅 SDK 文档。

响应

下面是响应的示例，其中包括 一个 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


// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Me.MailFolders.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.IncludeHiddenFolders = "true";
});

重要

有关如何将 SDK 添加到项目并创建 authProvider 实例的详细信息，请参阅 SDK 文档。


// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc-beta users mail-folders list --user-id {user-id} --include-hidden-folders "true"

重要

有关如何将 SDK 添加到项目并创建 authProvider 实例的详细信息，请参阅 SDK 文档。



import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
	  graphusers "github.com/microsoftgraph/msgraph-beta-sdk-go/users"
	  //other-imports
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)



requestIncludeHiddenFolders := "true"

requestParameters := &graphusers.ItemMailFoldersRequestBuilderGetQueryParameters{
	IncludeHiddenFolders: &requestIncludeHiddenFolders,
}
configuration := &graphusers.ItemMailFoldersRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

mailFolders, err := graphClient.Me().MailFolders().Get(context.Background(), configuration)

重要

有关如何将 SDK 添加到项目并创建 authProvider 实例的详细信息，请参阅 SDK 文档。


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

MailFolderCollectionResponse result = graphClient.me().mailFolders().get(requestConfiguration -> {
	requestConfiguration.queryParameters.includeHiddenFolders = "true";
});

重要

有关如何将 SDK 添加到项目并创建 authProvider 实例的详细信息，请参阅 SDK 文档。


const options = {
	authProvider,
};

const client = Client.init(options);

let mailFolders = await client.api('/me/mailFolders/?includeHiddenFolders=true')
	.version('beta')
	.get();

重要

有关如何将 SDK 添加到项目并创建 authProvider 实例的详细信息，请参阅 SDK 文档。


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Users\Item\MailFolders\MailFoldersRequestBuilderGetRequestConfiguration;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestConfiguration = new MailFoldersRequestBuilderGetRequestConfiguration();
$queryParameters = MailFoldersRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->includeHiddenFolders = "true";
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->me()->mailFolders()->get($requestConfiguration)->wait();

重要

有关如何将 SDK 添加到项目并创建 authProvider 实例的详细信息，请参阅 SDK 文档。


Import-Module Microsoft.Graph.Beta.Mail

# A UPN can also be used as -UserId.
Get-MgBetaUserMailFolder -UserId $userId -Includehiddenfolders true

重要

有关如何将 SDK 添加到项目并创建 authProvider 实例的详细信息，请参阅 SDK 文档。


from msgraph import GraphServiceClient
from msgraph.generated.users.item.mail_folders.mail_folders_request_builder import MailFoldersRequestBuilder

graph_client = GraphServiceClient(credentials, scopes)

query_params = MailFoldersRequestBuilder.MailFoldersRequestBuilderGetQueryParameters(
		include_hidden_folders = "true",
)

request_configuration = MailFoldersRequestBuilder.MailFoldersRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.me.mail_folders.get(request_configuration = request_configuration)

重要

有关如何将 SDK 添加到项目并创建 authProvider 实例的详细信息，请参阅 SDK 文档。

响应

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

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

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
        }
    ]
}

列出 mailFolder

权限

HTTP 请求

可选的查询参数

请求标头

请求正文

响应

示例

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

请求

响应

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

请求

响应

反馈

反馈

其他资源