列出邮件
命名空间: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
响应
以下示例显示了相应的响应。 若要获取下一页邮件,请将 @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"
}
}
}
]
}
反馈
https://aka.ms/ContentUserFeedback。
即将推出:在整个 2024 年,我们将逐步取消以“GitHub 问题”作为内容的反馈机制,并将其替换为新的反馈系统。 有关详细信息,请参阅:提交和查看相关反馈