列出邮件
本文内容
命名空间:microsoft.graph
获取登录用户的邮箱(包括“已删除邮件”和“待筛选邮件”文件夹)中的邮件。
根据页面大小和邮箱数据,从邮箱中获取邮件可能会引发多个请求。 默认页面大小为 10 封邮件。 使用 $top
以自定义页面大小(范围在 1 - 1000 之间)。
若要改进操作响应时间,请使用 $select
指定所需的精确属性;请参阅下方 示例 1 。 微调 $select
和 $top
的值,尤其在必须使用较大的页面大小时,因为返回带有数百条邮件(且每条邮件都有完整的响应有效负载) 的页面可能触发 网关超时 (HTTP 504)。
若要获取下一页的邮件,只需将 @odata.nextLink
中返回的整个 URL 应用于下一个 get-messages 请求。 此 URL 包括可能已在初始请求中指定的任何查询参数。
不要尝试从 @odata.nextLink
URL 中提取 $skip
值来操纵响应。 此 API 使用 $skip
值来保留其已在用户邮箱中遍历的所有项的计数,以返回 message-type 项的页面。 因此,甚至在初始响应中,$skip
值都会大于页面大小。 有关详细信息,请参阅在应用中对 Microsoft Graph 数据进行分页 。
目前,此操作返回纯 HTML 格式的邮件正文。
在以下两种情况下,应用可以获取其他用户的邮件文件夹中的邮件:
如果该应用具有应用程序权限,或者
如果应用具有来自某个用户的相应委派权限 ,而另一个用户与该用户共享了邮件文件夹,或者已为该用户授予委派的访问权限。 请参阅详细信息和示例 。
此 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/messages
GET /users/{id | userPrincipalName}/messages
若要获取用户邮箱中特定文件夹中的邮件,请执行以下操作:
GET /me/mailFolders/{id}/messages
GET /users/{id | userPrincipalName}/mailFolders/{id}/messages
可选的查询参数
此方法支持 OData 查询参数 来帮助自定义响应。
在同一查询中使用 filter 和 orderby
在同一查询中使用 $filter
和 $orderby
获取消息时,请确保按以下方式指定属性:
$orderby
中显示的属性也必须在 $filter
中显示。
$orderby
中显示的属性与 $filter
中属性的顺序相同。
$orderby
中存在的属性显示在 $filter
中不存在的任意属性之前。
无法进行此项操作时会导致下列错误:
错误代码:InefficientFilter
错误消息:The restriction or sort order is too complex for this operation.
名称
类型
说明
Authorization
string
持有者 {token}。 必填。
Prefer: outlook.body-content-type
string
要返回的 body 和 uniqueBody 属性的格式。 可取值为“text”或“html”。 如果未指定此头,采用 HTML 格式返回 body 和 uniqueBody 属性。 可选。
请求正文
请勿提供此方法的请求正文。
响应
如果成功,此方法在响应正文中返回 200 OK
响应代码和 Message 对象集合。
示例
示例 1:列出所有邮件
请求
下面显示了一个示例,该示例获取已登录用户邮箱中默认的前 10 封邮件。 它使用 $select
在响应中返回每封邮件的属性的子集。
GET https://graph.microsoft.com/v1.0/me/messages?$select=sender,subject
// 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.Messages.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Select = new string []{ "sender","subject" };
});
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users messages list --user-id {user-id} --select "sender,subject"
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
//other-imports
)
graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)
requestParameters := &graphusers.ItemMessagesRequestBuilderGetQueryParameters{
Select: [] string {"sender","subject"},
}
configuration := &graphusers.ItemMessagesRequestBuilderGetRequestConfiguration{
QueryParameters: requestParameters,
}
messages, err := graphClient.Me().Messages().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);
MessageCollectionResponse result = graphClient.me().messages().get(requestConfiguration -> {
requestConfiguration.queryParameters.select = new String []{"sender", "subject"};
});
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
const options = {
authProvider,
};
const client = Client.init(options);
let messages = await client.api('/me/messages')
.select('sender,subject')
.get();
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Users\Item\Messages\MessagesRequestBuilderGetRequestConfiguration;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestConfiguration = new MessagesRequestBuilderGetRequestConfiguration();
$queryParameters = MessagesRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->select = ["sender","subject"];
$requestConfiguration->queryParameters = $queryParameters;
$result = $graphServiceClient->me()->messages()->get($requestConfiguration)->wait();
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
Import-Module Microsoft.Graph.Mail
# A UPN can also be used as -UserId.
Get-MgUserMessage -UserId $userId -Property "sender,subject"
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
from msgraph import GraphServiceClient
from msgraph.generated.users.item.messages.messages_request_builder import MessagesRequestBuilder
graph_client = GraphServiceClient(credentials, scopes)
query_params = MessagesRequestBuilder.MessagesRequestBuilderGetQueryParameters(
select = ["sender","subject"],
)
request_configuration = MessagesRequestBuilder.MessagesRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)
result = await graph_client.me.messages.get(request_configuration = request_configuration)
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
响应
以下示例显示了相应的响应。 若要获取下一页邮件,请将 @odata.nextLink
中返回的 URL 应用 于后续 GET 请求。
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('bb8775a4-4d8c-42cf-a1d4-4d58c2bb668f')/messages(sender,subject)",
"value": [
{
"@odata.etag": "W/\"CQAAABYAAADHcgC8Hl9tRZ/hc1wEUs1TAAAwR4Hg\"",
"id": "AAMkAGUAAAwTW09AAA=",
"subject": "You have late tasks!",
"sender": {
"emailAddress": {
"name": "Microsoft Planner",
"address": "noreply@Planner.Office365.com"
}
}
}
]
}