命名空间：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 文档。
// Code snippets are only available for the latest major version. Current major version is $v1.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
//other-imports
)
requestParameters := &graphusers.ItemMessagesRequestBuilderGetQueryParameters{
Select: [] string {"sender","subject"},
}
configuration := &graphusers.ItemMessagesRequestBuilderGetRequestConfiguration{
QueryParameters: requestParameters,
}
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
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 文档。
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.users.item.messages.messages_request_builder import MessagesRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
query_params = MessagesRequestBuilder.MessagesRequestBuilderGetQueryParameters(
select = ["sender","subject"],
)
request_configuration = RequestConfiguration(
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"
}
}
}
]
}