邮件、日历、联系人和任务 REST API（版本 1.0）的资源参考
适用于：Exchange Online | Office 365 | Hotmail.com | Live.com | MSN.com | Outlook.com | Passport.com
备注
Outlook REST API 的版本 1.0 正被弃用。 自 2018 年 11 月 1 日 开始，应用将无法再在 1.0 版 REST 端点上使用基本身份验证。 截止到 2019 年 11 月 1 日，1.0 版 REST 端点将完全停用，并且 1.0 版文档将在不久之后移除。 请开始迁移你的应用，以便在 Microsoft Graph 1.0 版中使用 Outlook REST API。 更多详情，请参阅我们的通知。
本文介绍的 REST API 实体、属性、复杂类型、枚举和 OData 查询参数可用于 Outlook 邮件、日历、联系人和任务 API，以便访问 Office 365、Hotmail.com、Live.com、MSN.com、Outlook.com 和 Passport.com。
备注
为简便起见，本文的其余部分使用 Outlook.com 来指代这些 Microsoft 帐户域。
有关 Outlook REST API 所有子集的更多信息，请参阅使用 Outlook REST API。
对 API 的 1.0 版不感兴趣？ 在左侧的目录中，转到 Office 365 REST API 参考部分，然后选择所需的版本。
提示
你可以通过在 Web 浏览器中导航到 $metadata 端点（例如：https://outlook.office.com/api/v1.0/$metadata），查看邮件、日历、联系人和任务实体数据模型的完整元数据文档。
附件
附加到 事件、邮件或任务的一个文件或项目（联系、事件或消息）。 主题
相应的 fileAttachment 和 itemAttachment 资源都派生自附件资源。
类型：Microsoft.OutlookServices.Entity
| 属性 | 类型 | 说明 | 可写入？ | 可筛选？ | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ContentType | 字符串 | 附件的 MIME 类型。 | 是 | 否 | ||||||||||||
| IsInline | 布尔 | true |
UNTRANSLATED_CONTENT_START | if the attachment is an inline attachment; otherwise, false. |
UNTRANSLATED_CONTENT_END | 是 | 是 | |||||||||
| LastModifiedDateTime | DateTimeOffset | 上次修改附件的日期和时间。 日期和时间使用 ISO 8601 格式，并始终以 UTC 时间表示。 例如，2014 年 1 月 1 日午夜 UTC 将形如：'2014-01-01T00:00:00Z' |
否 | 是 | ||||||||||||
| 名称 | 字符串 | 附件的显示名称。 不必是实际的文件名。 | 是 | 是 | ||||||||||||
| 大小 | Int32 | 附件大小，以字节为单位。 | 否 | 否 |
日历
日历即事件容器。
类型：Microsoft.OutlookServices.Calendar
Calendar 集合在 OData 响应的 value 属性中返回日历数组。 使用 $count 以获得集合中实体的数量： .../me/calendars/$count
请参阅 Calendar操作以了解支持的操作。
| 属性 | 类型 | 说明 | 可写入？ | 可筛选？ |
|---|---|---|---|---|
| 名称 | 字符串 | 日历名称。 | 是 | 是 |
| ChangeKey | 字符串 | 识别日历对象的版本。 每次日历发生变化时，ChangeKey 都会更改。 它使得 Exchange 能将更改应用于正确版本的对象。 | 否 | 否 |
| 颜色 | CalendarColor | 在 UI 中指定将该日历与其他日历区分开来的颜色主题。属性值有：LightBlue=0、LightGreen=1、LightOrange=2、LightGray=3、LightYellow=4、LightTeal=5、LightPink=6、LightBrown=7、LightRed=8、MaxColor=9、Auto=-1 | 是 | 是 |
| Id | 字符串 | 日历的唯一标识符。 | 否 | 否 |
| CalendarView | 集合 (Event) | 日历的日历视图。 这是一个导航属性。 | 否 | 否 |
| 事件 | 集合 (Event) | 日历中的事件。 这是一个导航属性。 | 否 | 否 |
CalendarGroup
一组日历。
备注
Outlook.com 仅支持可通过 ../me/calendars 快捷方式访问的默认日历组。 您无法删除该日历组。
类型：Microsoft.OutlookServices.CalendarGroup
CalendarGroup 集合返回 OData 响应中 value 属性的一组日历组。 使用 $count 以获得集合中实体的数量： .../me/calendargroups/$count
请参阅 CalendarGroup 操作以了解支持的操作。
| 属性 | 类型 | 说明 | 可写入？ | 可筛选？ |
|---|---|---|---|---|
| 名称 | 字符串 | 组名称。 | 是 | 是 |
| ChangeKey | 字符串 | 标识日历组的版本。 每次日历组发生变化时，ChangeKey 都会更改。 它使得 Exchange 能将更改应用于正确版本的对象。 | 否 | 否 |
| ClassId | 字符串 | 类标识符。 | 否 | 是 |
| Id | 字符串 | 日历组的唯一标识符。 | 否 | 否 |
| 日历 | 集合 (Calendar) | 日历组中的日历。 这是一个导航属性。 | 否 | 否 |
联系人
联系人是 Outlook 中的一个项目，让用户组织和保存与他们通信的人员和组织的信息。 联系人包含在联系人文件夹中。
类型：Microsoft.OutlookServices.Contact
Contact 集合返回 OData 响应中 value 属性的联系人数组。 使用 $count 以获得集合中实体的数量： .../me/contacts/$count
请参阅 Contact 操作以了解支持的操作。
| 属性 | 类型 | 说明 | 可写入？ | 可筛选？ |
|---|---|---|---|---|
| AssistantName | 字符串 | 联系人助理的姓名。 | 是 | 是 |
| Birthday | datetimeoffset | 联系人的生日。 | 是 | 是 |
| BusinessAddress | PhysicalAddress | 联系人的公司地址。 | 是 | 是 |
| BusinessHomePage | 字符串 | 联系人的公司主页。 | 是 | 是 |
| BusinessPhones | 集合（字符串） | 联系人的公司电话号码。 | 是 | 否 |
| 类别 | 集合（字符串） | 与联系人关联的类别。 | 是 | 否 |
| ChangeKey | 字符串 | 标识联系人的版本。 每次联系人发生变化时，ChangeKey 都会更改。 它使得 Exchange 能将更改应用于正确版本的对象。 | 否 | 否 |
| Children | 集合（字符串） | 联系人子女的姓名。 | 是 | 是 |
| CompanyName | 字符串 | 联系人所在公司的名称。 | 是 | 是 |
| Department | 字符串 | 联系人所在的部门。 | 是 | 是 |
| DateTimeCreated | datetimeoffset | 联系人的创建时间。 | 否 | 是 |
| DateTimeLastModified | datetimeoffset | 联系人的修改时间。 | 否 | 是 |
| DisplayName | 字符串 | 联系人的显示名称。 | 是 | 是 |
| EmailAddresses | 集合 (EmailAddress) | 联系人的电子邮件地址。 | 是 | 否 |
| FileAs | 字符串 | 联系人备案的姓名。 | 是 | 是 |
| Generation | 字符串 | 联系人所属的代。 | 是 | 是 |
| GivenName | 字符串 | 联系人的名。 | 是 | 是 |
| HomeAddress | PhysicalAddress | 联系人的住宅地址。 | 是 | 是 |
| HomePhones | 集合（字符串） | 联系人的住宅电话号码。 | 是 | 否 |
| Id | 字符串 | 联系人的唯一标识符。 | 否 | 否 |
| ImAddresses | 集合（字符串） | 联系人的即时消息 (IM) 地址。 | 是 | 否 |
| Initials | 字符串 | 联系人的姓名缩写。 | 是 | 是 |
| JobTitle | 字符串 | 联系人的职务。 | 是 | 是 |
| Manager | 字符串 | 联系人经理的姓名。 | 是 | 是 |
| MiddleName | 字符串 | 联系人的中间名。 | 是 | 是 |
| MobilePhone1 | 字符串 | 联系人的移动电话号码。 | 是 | 是 |
| NickName | 字符串 | 联系人的昵称。 | 是 | 是 |
| OfficeLocation | 字符串 | 联系人的办公室位置。 | 是 | 是 |
| OtherAddress | PhysicalAddress | 联系人的其他地址。 | 是 | 是 |
| ParentFolderId | 字符串 | 联系人的父文件夹 ID。 | 否 | 否 |
| PersonalNotes | 字符串 | 有关联系人的用户备注。 | 是 | 是 |
| Profession | 字符串 | 联系人的职业。 | 是 | 是 |
| SpouseName | 字符串 | 联系人配偶的姓名。 | 是 | 是 |
| Surname | 字符串 | 联系人的姓氏。 | 是 | 是 |
| 标题 | 字符串 | 联系人的职位。 | 是 | 否 |
| YomiCompanyName | 字符串 | 联系人的注音日文公司名称。此属性是可选的。 | 是 | 否 |
| YomiGivenName | 字符串 | 联系人的注音日文名字。此属性是可选的。 | 是 | 否 |
| YomiSurname | 字符串 | 联系人的注音日文姓氏。此属性是可选的。 | 是 | 否 |
ContactFolder
包含联系人的文件夹。
类型：Microsoft.OutlookServices.ContactFolder
ContactFolder 集合在 OData 响应的 value 属性中返回联系人文件夹数组。 使用 $count 以获得集合中实体的数量： .../me/contactfolders/$count
请参阅 ContactFolder 操作以了解支持的操作。
| 属性 | 类型 | 说明 | 可写入？ | 可筛选？ |
|---|---|---|---|---|
| ChildFolders | 集合 (ContactFolder) | 文件夹中的子文件夹的集合。 这是一个导航属性。 | 否 | 否 |
| 联系人 | 集合 (Contact) | 文件夹中的联系人。 这是一个导航属性。 | 否 | 否 |
| DisplayName | 字符串 | 文件夹的显示名称。 | 是 | 是 |
| Id | 字符串 | 联系人文件夹的唯一标识符。 | 否 | 否 |
| ParentFolderId | 字符串 | 文件夹的父文件夹 ID。 | 否 | 否 |
事件
日历中的事件。
类型：Microsoft.OutlookServices.Event
一个 Event 集合在 OData 响应的 value 属性中返回事件的数组。 使用 $count 以获得集合中实体的数量： .../me/events/$count
请参阅 Event 操作以了解支持的操作。
| 属性 | 类型 | 说明 | 可写入？ | 可筛选？ |
|---|---|---|---|---|
| 附件 | 集合 (Attachment) | 事件的 FileAttachment 和 ItemAttachment 附件。 这是一个导航属性。 | 否 | 否 |
| Attendees | 集合 (Attendee) | 事件的与会者集合。 | 是 | 否 |
| Body | ItemBody | 与事件相关联的邮件正文。 | 是 | 否 |
| BodyPreview | 字符串 | 与事件相关联的邮件预览。 | 否 | 否 |
| 日历 | 日历 | 包含事件的日历。 这是一个导航属性。 | 否 | 否 |
| 类别 | 集合（字符串） | 与事件相关联的类别。 | 是 | 否 |
| ChangeKey | 字符串 | 标识 event 对象的版本。每次事件更改时，ChangeKey 也将更改。这样，Exchange 可以将更改应用于该对象的正确版本。 | 否 | 否 |
| DateTimeCreated | datetimeoffset | 事件创建的日期和时间。 | 否 | 是 |
| DateTimeLastModified | datetimeoffset | 事件上次修改的日期和时间。 | 否 | 是 |
| End | datetimeoffset | 事件的结束日期和时间。 默认情况下，结束时间使用 UTC 格式。可以在 EndTimeZone 中指定可选的时区，用该时区表示结束时间并包括与 UTC 的时间偏移量。请注意，如果使用 EndTimeZone，必须为 StartTimeZone 指定一个值。 本示例指定太平洋标准时间的 2015 年 2 月 25 日晚上 9:34：“2015-02-25T21:34:00-08:00”。 |
是 | 是 |
| EndTimeZone | 字符串 | 标识会议结束时间的会议时区（请参阅“结束”属性）。 该属性按照存储在 Windows 中的时区名称进行设置。 您可以通过调用 System.TimeZoneInfo.GetSystemTimeZones() 来获取时区名称。 对于 v1.0，该属性为可选。 但是，如果使用了 StartTimeZone 属性，则必须使用此属性。 有关更多信息，请参阅 TimeZone。 |
是 | 否 |
| HasAttachments | 布尔值 | 如果事件包含附件，则设置为 true。 | 否 | 是 |
| Id | 字符串 | 事件的唯一标识符。 | 否 | 否 |
| Importance | Importance | 事件的重要性：Low、Normal、High。 |
是 | 是 |
| Instances | 集合 (Event) | 事件的实例。 这是一个导航属性。 | 否 | 否 |
| iCalUID | 字符串 | 由不同日历间的所有事件实例共享的唯一标识符。 | 否 | 是 |
| IsAllDay | 布尔值 | 如果事件持续一整天，则设置为 true。 调整此属性还需要调整 Start 和 End 事件的属性。 | 是 | 是 |
| IsCancelled | 布尔值 | 如果事件已取消，则设置为 true。 | 是 | 是 |
| IsOrganizer | 布尔值 | 如果邮件发件人也是组织者，则设置为 true。 | 是 | 是 |
| Location | Location | 事件的位置。 | 是 | 是 |
| Organizer | Recipient | 事件的组织者。 | 是 | 是 |
| 定期 | PatternedRecurrence | 事件的定期模式。 | 是 | 否 |
| ResponseRequested | 布尔值 | 如果发件人希望接收事件被接受或拒绝时的响应，则设置为 true。 | 是 | 是 |
| ResponseStatus | ResponseStatus | 指示在事件消息的响应中发送的响应类型。 | 否 | 是 |
| Sensitivity | Sensitivity | 指示事件的隐私级别：正常 = 0，个人 = 1，隐私 = 2，机密 = 3。 | 是 | 是 |
| SeriesMasterId | 字符串 | 分配给项目的类别。 | 是 | 否 |
| ShowAs | FreeBusyStatus | 要显示的状态：空闲 = 0，暂定 = 1，忙碌 = 2，Oof = 3，WorkingElsewhere = 4，未知 = -1。 | 是 | 是 |
| 开始 | datetimeoffset | 事件的开始时间。 默认情况下，开始时间使用 UTC 格式。可以在 StartTimeZone 中指定可选的时区，用该时区表示开始时间并包括与 UTC 的时间偏移量。请注意，如果使用 StartTimeZone，你也必须为 EndTimeZone 指定一个值。 本示例指定太平洋标准时间的 2015 年 2 月 25 日晚上 7:34：“2015-02-25T19:34:00-08:00”。 |
是 | 是 |
| StartTimeZone | 字符串 | 标识会议开始时间的会议时区（请参阅 Start 属性）。 这个属性使得服务处理时区发生变化而不是由客户端处理。 该属性按照存储在 Windows 中的时区名称进行设置。 您可以通过调用 System.TimeZoneInfo.GetSystemTimeZones() 来获取时区名称。 对于 v1.0，该属性为可选。 但是，如果使用了 EndTimeZone 属性，则必须使用此属性。 此属性的示例值为“太平洋标准时间”。 有关更多信息，请参阅 TimeZone。 |
是 | 否 |
| Subject | 字符串 | 事件的主题行文本。 | 是 | 是 |
| 类型 | EventType | 事件类型：SingleInstance = 0，Occurrence = 1，Exception = 2，SeriesMaster = 3。 | 是 | 是 |
| WebLink | 字符串 | 要在 Outlook Web App 中打开事件的 URL。 如果你通过 Outlook Web App 登录邮箱，该事件将在浏览器中打开。如果尚未使用浏览器登录，系统将提示你登录。 可以从 iFrame 中访问此 URL。 |
否 | 否 |
EventMessage
消息表示会议请求、会议取消消息、会议接受消息、会议暂时接受消息或会议谢绝消息。
基本类型：Message
EventMessage 实例通常位于其收到的收件箱文件夹中，作为活动组织者创建会议或与会者响应会议请求的结果。 可以采用与处理 Message 相同的方式来处理事件消息，但存在一些细微的差异，具体如下表所述。
| 操作/动词 | 权限 | 说明 |
|---|---|---|
| 创建事件消息 (POST) | 无 | 不允许。 将产生一个 400 响应代码。 |
| 更新事件消息 (PATCH) | Mail.Write | 你可以更新以下属性：From、Sender、ToRecipients、CcRecipients、BccRecipients、ReplyTo、IsDeliveryReceiptRequested、IsReadReceiptRequested、IsDraft、IsRead、Subject、Body、Importance 和 Categories。 |
| 删除事件消息 (DELETE) | Mail.Write | 与针对 Message 的操作相同。 |
| 移动事件消息 (POST) | Mail.Write | 与针对 Message 的操作相同。 |
| 复制事件消息 (POST) | Mail.Write | 与针对 Message 的操作相同。 |
| 创建答复消息草稿 (POST) | Mail.Write | 与针对 Message 的操作相同。 |
| 创建全部答复信息草稿 (POST) | Mail.Write | 与针对 Message 的操作相同。 |
| 创建一个答复 (POST) | Mail.Write | 与针对 Message 的操作相同。 |
| 创建一个全部答复 (POST) | Mail.Write | 与针对 Message 的操作相同。 |
| 发送一个现有事件消息 (POST) | Mail.Write | 你只能发送 IsDraft 属性值为 true 的事件消息。 消息副本保存在“已发送邮件”文件夹中。 |
| 创建转发事件消息草稿 | Mail.Write | 与针对 Message 的操作相同。 |
| 转发事件消息 | Mail.Write | 与针对 Message 的操作相同。 |
一个 EventMessage 实例包含基本类型Message 的属性以及下表中的属性。
| 属性 | 类型 | 说明 | 可写入？ | 可筛选？ |
|---|---|---|---|---|
| 事件 | 事件 | 与事件消息关联的事件。 对于与会者或会议室资源，假定已将日历助理设为在会议请求事件消息到达时自动更新包含事件的日历。 这是一个导航属性。 | 否 | 否 |
| MeetingMessageType | MeetingMessageType | 事件消息的类型：None= 0，MeetingRequest = 1，MeetingCancelled = 2，MeetingAccepted = 3，MeetingTentativelyAccepted = 4，MeetingDeclined = 5 | 否 | 是 |
EventMessageRequest（预览）
这个功能目前在 beta 版中可用。 要了解详细信息，请在左侧的目录中转到 Office 365 REST API 参考部分，并选择 beta。
扩展属性
这个功能目前在 beta 版和 V2.0 版可用。 要了解详细信息，请在左侧的目录中转到 Office 365 REST API 参考部分，并选择所需版本。
FileAttachment
附加到邮件或事件的文件（例如文本文件或 Word 文档）。 ContentBytes 属性包含文件的 base64 编码内容。 派生自 Attachment 实体。
类型：Microsoft.OutlookServices.FileAttachment
基本类型：Microsoft.OutlookServices.Attachment
| 属性 | 类型 | 说明 | 可写入？ |
|---|---|---|---|
| ContentBytes | 二进制 | 文件的二进制内容。 | 否 |
| ContentId | 字符串 | 获取 Exchange 存储中的附件 ID。 | 否 |
| ContentLocation | 字符串 | 对应于附件内容所在位置的统一资源标识符 (URI)。 | 否 |
| ContentType | 字符串 | 附件的内容类型。 | 是 |
| DateTimeLastModified | datetimeoffset | 上次修改附件的日期和时间。 | 否 |
| Id | 字符串 | 附件 ID。 | 否 |
| IsContactPhoto | 布尔值 | 过时。 | 是 |
| IsInline | 布尔值 | 如果是内嵌附件则设置为 true。 | 是 |
| 名称 | 字符串 | 表示显示在表示嵌入的附件的图标下方的文本的名称。该名称不必是实际的文件名。 | 是 |
| 大小 | Int32 | 附件大小，以字节为单位。 | 否 |
Folder / MailFolder
备注
在 v1.0 之后的版本中，Folder 实体和类型已重命名为 MailFolder。
用户邮箱中的文件夹，例如收件箱、草稿箱和已发送邮件。 文件夹可以包含邮件和其他文件夹。
类型： Microsoft.OutlookServices.Folder
Folders 集合在 OData 响应的 value 属性中返回文件夹数组。 使用 $count 以获得集合中实体的数量： .../me/folders/$count
请参阅 Folder 操作以了解支持的操作。
| 属性 | 类型 | 说明 | 可写入？ | 可筛选？ |
|---|---|---|---|---|
| ChildFolderCount | Int32 | 文件夹中的文件夹数量。 | 否 | 是 |
| ChildFolders | 集合 (Folder) | 文件夹中的子文件夹的集合。 这是一个导航属性。 | 否 | 否 |
| DisplayName | 字符串 | 文件夹的显示名称。 | 是 | 是 |
| Id | 字符串 | 该文件夹的唯一标识符。 你可以使用以下知名名称访问相应的文件夹：收件箱、草稿、已发送邮件、已删除邮件。 | 否 | 否 |
| 邮件 | 集合 (Message) | 文件夹中的邮件集合。 这是一个导航属性。 | 否 | 否 |
| ParentFolderId | 字符串 | 该文件的父文件夹的唯一标识符。 | 否 | 否 |
| TotalItemCount | Int32 | 文件夹中的项目数量。 | 否 | 是 |
| UnreadItemCount | Int32 | 文件夹中标记为未读项的数量。 | 否 | 是 |
有效的访问项计数
文件夹的 TotalItemCount 和 UnreadItemCount 属性允许你方便地计算文件夹中读取项目的数量。 它们让你避免像下面这样会引起严重延迟的查询：
https://outlook.office.com/api/v1.0/me/folders/inbox/messages?$count=true&$filter=isread%20eq%20false
Outlook 中的 Folders 可包含多个类型的项，例如，收件箱可以包含不同于邮件项的会议请求项。 TotalItemCount 和 UnreadItemCount 会计入文件夹中的项目，而无论项目的类型如何。
InferenceClassification
这个功能目前在 v2.0 版和测试版可用。 要了解详细信息，在左侧的目录转到 Office 365 REST API 引用部分，并选择以下版本之一。
InferenceClassificationOverride
这个功能目前在 v2.0 版和测试版可用。 要了解详细信息，在左侧的目录转到 Office 365 REST API 引用部分，并选择以下版本之一。
ItemAttachment
与另一个邮件或事件相关的邮件、联系人或事件。 派生自 Attachment 实体。
类型：Microsoft.OutlookServices.ItemAttachment
基本类型：Microsoft.OutlookServices.Attachment
| 属性 | 类型 | 说明 | 可写入？ |
|---|---|---|---|
| ContentType | 字符串 | 附件的内容类型。 | 是 |
| DateTimeLastModified | datetimeoffset | 上次修改附件的时间和日期。 | 否 |
| Id | 字符串 | 附件 ID。 | 否 |
| Item | Item | 附加的消息或事件。导航属性。 | 是 |
| IsInline | 布尔值 | 如果附件是内联的（例如嵌入到项目正文中的图像），请设置为 true。 | 是 |
| 名称 | 字符串 | 附件的显示名称。 | 是 |
| 大小 | Int32 | 附件大小，以字节为单位。 | 是 |
Mention（预览）
此功能目前只在 beta 版中可用。 要了解详细信息，请在左侧的目录中转到 Office 365 REST API 参考部分，并选择 beta。
邮件
邮箱文件夹中的邮件。
类型：Microsoft.OutlookServices.Message
消息集合在 OData 响应的 value 属性中返回邮件数组。 使用 $count 以获得集合中实体的数量： .../me/messages/$count
请参阅 Message 操作以了解支持的操作。
| 属性 | 类型 | 说明 | 可写入？ | 可筛选？ | 可搜索？ |
|---|---|---|---|---|---|
| 附件 | 集合 (Attachment) | 邮件的 fileAttachment 和 itemAttachment 附件。 这是一个导航属性。 | 是 | 否 | 是 |
| BccRecipients | 集合 (Recipient) | 邮件的秘密抄送收件人。 | 是 | 否 | 是 |
| Body | ItemBody | 邮件的正文。 | 是 | 否 | 默认 |
| BodyPreview | 字符串 | 邮件正文内容的前 255 个字符。 | 否 | 否 | 是 |
| 类别 | 集合（字符串） | 与邮件关联的类别。 | 是 | 是 | 是 |
| CcRecipients | 集合 (Recipient) | 邮件的抄送收件人。 | 是 | 否 | 是 |
| ChangeKey | 字符串 | 邮件的版本。 | 否 | 否 | 否 |
| ConversationId | 字符串 | 电子邮件所属的对话的 ID。 | 否 | 是 | 否 |
| DateTimeCreated | datetimeoffset | 创建邮件的日期和时间。 | 否 | 是 | 否 |
| DateTimeLastModified | datetimeoffset | 上次更改邮件的日期和时间。 | 否 | 是 | 否 |
| DateTimeReceived | datetimeoffset | 收到邮件的日期和时间。 | 否 | 是 | 是 |
| DateTimeSent | datetimeoffset | 发送邮件的日期和时间。 | 否 | 是 | 否 |
| From | Recipient | 邮箱所有者和邮件发件人。 | 是 | 是 | 是 |
| HasAttachments | 布尔值 | 指示邮件是否包含附件。 | 是 | 是 | 是 |
| Id | 字符串 | 邮件的唯一标识符。 | 否 | 否 | 否 |
| Importance | Importance | 邮件的重要性：低 = 0，正常 = 1，高 = 2。 | 是 | 是 | 是 |
| IsDeliveryReceiptRequested | 布尔值 | 指示是否需要发送邮件已读回执。 | 是 | 是 | 否 |
| IsDraft | 布尔值 | 指示邮件是否为草稿。如果尚未发送，则此邮件是一封草稿。 | 否 | 是 | 否 |
| IsRead | 布尔值 | 指示是否已阅读该邮件。 | 是 | 是 | 否 |
| IsReadReceiptRequested | 布尔值 | 指示是否需要发送邮件已读回执。 | 是 | 是 | 否 |
| ParentFolderId | 字符串 | 该邮件的父文件夹的唯一标识符。 | 否 | 否 | 否 |
| ReplyTo | 集合 (Recipient) | 在答复时使用的电子邮件地址。 | 是 | 否 | 否 |
| Sender | Recipient | 实际用于生成邮件的帐户。 | 是 | 是 | 默认设置 |
| Subject | 字符串 | 邮件的主题。 | 是 | 是 | 默认设置 |
| ToRecipients | 集合 (Recipient) | 邮件的收件人。 | 是 | 否 | 是 |
| UniqueBody | ItemBody | 对话专用的邮件正文部分。 | 否 | 否 | 否 |
| WebLink | 字符串 | 要在 Outlook Web App 中打开邮件的 URL。 可以将 ispopout 参数附加到此 URL 的末尾以更改邮件的显示方式。如果 ispopout 不存在或设置为 1，则邮件显示在弹出窗口中。如果 ispopout 设置为 0，则浏览器将在 Outlook Web App 审阅窗格中显示邮件。 如果通过 Outlook Web App 登录邮箱，该邮件将在浏览器中打开。如果尚未使用浏览器登录，系统将提示你登录。 可以从 iFrame 中访问此 URL。 |
否 | 是 | 否 |
从 Body 属性中删除脚本
邮件正文可以是 HTML 或文本。 如果正文是 HTML 格式，默认情况下，在 REST 响应中返回正文内容之前，将删除嵌入 Body 属性中的任意具有潜在不安全性的 HTML（例如，JavaScript）。
要获取整个原始 HTML 内容，请包含以下 HTTP 请求标头：
Prefer: outlook.allow-unsafe-html
设置 From 和 Sender 属性
撰写邮件时，在大多数情况下，From 和 Sender 属性表示同一个已登录用户，除非其中一个属性已更新，如以下情况中所述：
如果 Exchange 管理员已将邮箱的 ** SendAs** 权限分配给其他用户，则可更改此 ** From** 属性。 通过在 Azure 管理门户中选择邮箱所有者的邮箱权限，或通过使用 Exchange 管理中心或 Windows PowerShell Add-ADPermission cmdlet，管理员可执行此操作。 然后，可以通过编程的方式将From 属性设置为拥有邮箱的 SendAs 权限的其中一个用户。
如果邮箱所有者已委派一个或多个用户能够从该邮箱发送邮件，则可以更改此 Sender 属性。 邮箱所有者可以在 Outlook 中进行委派。 当受托人代表邮箱所有者发送邮件时，Sender 属性已设置为受托人的帐户，但 From 属性仍然是邮箱所有者。 你可以通过编程的方式将 Sender 属性设置为给已经获得该邮箱的委托权的用户。
MessageRule（预览）
这个功能目前在 beta 版中可用。 要了解详细信息，请在左侧的目录中转到 Office 365 REST API 参考部分，并选择 beta。
OutlookCategory（预览）
这个功能目前在 beta 版中可用。 要了解详细信息，请在左侧的目录中转到 Office 365 REST API 参考部分，并选择 beta。
Photo
这个功能目前在 v2.0 版和测试版可用。 要了解详细信息，在左侧的目录转到 Office 365 REST API 引用部分，并选择以下版本之一。
ReferenceAttachment
这个功能目前在 beta 版中可用。 要了解详细信息，请在左侧的目录中转到 Office 365 REST API 参考部分，并选择 beta。
任务
这个功能目前在 beta 版和 V2.0 版可用。 要了解详细信息，在左侧的目录转到 Office 365 REST API 引用部分，并选择以下版本之一。
TaskFolder
这个功能目前在 beta 版和 V2.0 版可用。 要了解详细信息，在左侧的目录转到 Office 365 REST API 引用部分，并选择以下版本之一。
TaskGroup
这个功能目前在 beta 版和 V2.0 版可用。 要了解详细信息，在左侧的目录转到 Office 365 REST API 引用部分，并选择以下版本之一。
用户
系统中的用户。 Me 端点作为快捷方式提供，用于通过 SMTP 地址（users/sadie@contoso.com）指定当前用户。
类型：Microsoft.OutlookServices.User
|||UNTRANSLATED_CONTENT_START|||A Users collection returns an array of users in the value property of the OData response.|||UNTRANSLATED_CONTENT_END||| 使用 $count 以获得集合中实体的数量： .../me/users/$count
备注
User 实体包含频繁增强的许多属性和关系（导航属性）。 以下部分仅介绍一个子集。 要了解最新信息，请参阅适用于你的版本的相应** 元数据文件**中的 User 定义。
| 属性 | 类型 | 说明 | 可写入？ | 可筛选？ |
|---|---|---|---|---|
| 别名 | 字符串 | 用户的别名。 通常是用户的 SMTP 地址。 | 是 | 是 |
| 日历 | 日历 | 用户的主日历。 这是一个导航属性。 | 否 | 否 |
| CalendarGroups | 集合 (CalendarGroup) | 用户的日历组。 这是一个导航属性。 | 否 | 否 |
| 日历 | 集合 (Calendar) | 用户的日历。 这是一个导航属性。 | 否 | 否 |
| CalendarView | 集合 (Event) | 日历的日历视图。 这是一个导航属性。 | 否 | 否 |
| ContactFolders | 集合 (ContactFolder) | 用户的联系人文件夹。 这是一个导航属性。 | 否 | 否 |
| 联系人 | 集合 (Contact) | 用户的联系人。 这是一个导航属性。 | 否 | 否 |
| DisplayName | 字符串 | 用户的显示名称。 | 是 | 是 |
| 事件 | 集合 (Event) | 用户的事件。 默认为在默认日历下显示事件。 这是一个导航属性。 | 否 | 否 |
| 文件夹 | 集合 (Folder) | 邮箱或文件夹中的文件夹。 这是一个导航属性。 | 否 | 否 |
| Id | 字符串 | 用户的唯一标识符。 | 否 | 否 |
| MailboxGuid | guid | 分配给用户邮箱的 GUID。 | 否 | 是 |
| 邮件 | 集合 (Message) | 邮箱或文件夹中的邮件。 这是一个导航属性。 | 否 | 否 |
| RootFolder | 文件夹 | 用户邮箱的根文件夹。 这是一个导航属性。 | 否 | 否 |
复杂类型
- Attendee
- EmailAddress
- GeoCoordinates
- ItemBody
- Location
- PatternedRecurrence
- PhysicalAddress
- Recipient
- RecurrencePattern
- RecurrenceRange
- ResponseStatus
Attendee
会议与会者。
类型：Microsoft.OutlookServices.Recipient
| 属性 | 类型 | 说明 |
|---|---|---|
| 状态 | ResponseStatus | 响应（无、接受、拒绝等）和时间。 |
| 类型 | AttendeeType | 与会者的类型：Required、Optional、Resource。 |
EmailAddress
联系人或邮件收件人的姓名和电子邮件地址。
类型：Microsoft.OutlookServices.EmailAddress
| 属性 | 类型 | 说明 |
|---|---|---|
| 名称 | 字符串 | 人员或实体的显示名称。 |
| Address | 字符串 | 人员或实体的电子邮件地址。 |
GeoCoordinates
地理坐标和位置的海拔高度。
类型：Microsoft.OutlookServices.GeoCoordinates
| 属性 | 类型 | 说明 |
|---|---|---|
| Altitude | 翻倍 | 位置的海拔高度。 |
| Latitude | 翻倍 | 位置的纬度。 |
| Longitude | 翻倍 | 位置的经度。 |
| Accuracy | 翻倍 | 提供经纬度的传感器的准确性。 |
| AltitudeAccuracy | 翻倍 | 提供维度的传感器的准确性。 |
ItemBody
邮件或事件的正文内容。
类型：Microsoft.OutlookServices.ItemBody
| 属性 | 类型 | 说明 |
|---|---|---|
| ContentType | BodyType | 内容类型： Text = 0，HTML = 1。 |
| Content | 字符串 | 文本或 HTML 内容。 |
Location
事件的位置。
类型：Microsoft.OutlookServices.Location
| 属性 | 类型 | 说明 |
|---|---|---|
| DisplayName | 字符串 | 与地点相关联的名称。 |
| Address | PhysicalAddress | 位置的实际地址。 |
| 坐标 | GeoCoordinates | 地理坐标和位置的海拔高度。 |
PatternedRecurrence
定期模式和区域。
类型：Microsoft.OutlookServices.PatternedRecurrence
| 属性 | 类型 | 说明 |
|---|---|---|
| 模式 | RecurrencePattern | 事件发生的频率。 |
| Range | RecurrenceRange | 事件的持续时间。 |
PhysicalAddress
联系人的实际地址。
类型：Microsoft.OutlookServices.PhysicalAddress
| 属性 | 类型 | 说明 |
|---|---|---|
| Street | 字符串 | 街道。 |
| City | 字符串 | 城市。 |
| 状态 | 字符串 | 省/市/自治区。 |
| CountryOrRegion | 字符串 | 国家或地区。它是任意格式的字符串值，例如“United States”。 |
| PostalCode | 字符串 | 邮政编码。 |
Recipient
表示事件或邮件发送或接收端的用户相关信息。
类型：Microsoft.OutlookServices.Recipient
| 属性 | 类型 | 说明 |
|---|---|---|
| EmailAddress | EmailAddress | 收件人的电子邮件地址。 |
RecurrencePattern
事件发生的频率。
类型：Microsoft.OutlookServices.RecurrencePattern
| 属性 | 类型 | 说明 |
|---|---|---|
| 类型 | RecurrencePatternType | 定期模式类型：Daily = 0，Weekly = 1，AbsoluteMonthly = 2，RelativeMonthly = 3，AbsoluteYearly = 4，RelativeYearly = 5。 模式规则： - AbsoluteYearly。 必须设置发生的 Month 和 DayOfMonth - RelativeYearly。 必须设置 Month、DaysOfWeek 和 FirstDayOfWeek index - AbsoluteMonthly。 必须设置 DAYOFMONTH - RelativeMonthly。 必须设置 Firstdayofweek 指数和 RecurrenceRange.NumberOfOccurrences - Weekly。 必须设置 DaysOfWeek 和 Firstdayofweek - Daily。 无需额外的模式信息。 |
| 时间间隔 | Int32 | 两次发生之间的指定定期类型的单位数量。 |
| DayOfMonth | Int32 | 项目发生的月内日期。 |
| Month | Int32 | 项目发生的月份。 这是一个介于 1 到 12 之间的数字。 |
| DaysOfWeek | 集合 (DayOfWeek) | 星期几的集合：星期日= 0，星期一= 1，星期二= 2，星期三= 3，星期四= 4，星期五= 5，星期六= 6。 |
| FirstDayOfWeek | DayOfWeek | 星期几：星期日= 0，星期一= 1，星期二= 2，星期三= 3，星期四= 4，星期五= 5，星期六= 6。 |
| 索引 | WeekIndex | 星期索引：第一= 0，第二= 1，第三= 2，第四= 3，最后= 4。 |
RecurrenceRange
事件的持续时间。
类型：Microsoft.OutlookServices.RecurrenceRange
| 属性 | 类型 | 说明 |
|---|---|---|
| 类型 | RecurrenceRangeType | 重复范围：EndDate = 0，NoEnd = 1，Numbered = 2。 |
| StartDate | datetimeoffset | 必需：系列的开始日期。 |
| EndDate | datetimeoffset | 日期绑定模式必需：该系列的结束日期。 必须在开始日期之后。 |
| NumberOfOccurrences | Int32 | 编号模式必需：该事件重复多少次。 |
ResponseStatus
会议请求的响应状态。
类型：Microsoft.OutlookServices.ResponseStatus
| 属性 | 类型 | 说明 |
|---|---|---|
| 响应 | ResponseType | 响应类型：None、Organizer、TentativelyAccepted、Accepted、Declined、NotResponded。 |
| Time | datetimeoffset | 响应返回的日期和时间。 |
枚举
DayOfWeek
一周中的一天。
支持的值：
- 星期日
- 周一
- 周二
- 周三
- 周四
- 周五
- 周六
FreeBusyStatus
指定会议的与会者的忙闲状态。
支持的值：
- 忙碌
- 空闲
- Oof
- Tentative
- 未知
- WorkingElsewhere
ReferenceAttachmentPermissions
引用附件的文件或文件夹的访问权限。
支持的值：
- 其他
- 视图
- 编辑
- AnonymousView
- AnonymousEdit
- OrganizationView
- OrganizationEdit
ReferenceAttachmentProviders
引用附件可能的文件存储提供商。
支持的值：
- Dropbox
- OneDriveBusiness
- OneDriveConsumer
- 其他
Sensitivity
指示隐私级别。
支持的值：
- 常规
- 个人
- 私有
- 机密
OData 查询参数
你可以在使用邮件、日历和联系人 API 时使用标准 OData v4.0 查询参数来筛选数据请求，并对页面结果进行排序和分页。 指定查询参数时，确保为 URI 中的特殊含义保留的特殊字符已经适当编码。
$search按特定的标准搜索$filter按特定的标准筛选$select请求特定的属性$orderby对结果进行排序$top和对结果$skip进行分页$expand展开邮件附件和事件附件$count获得集合中实体的数量。 该参数位于 URL 路径中：.../me/calendars/$count
使用邮件、日历和联系人 API 执行的查询始终使用较浅的作用域。 只有当前文件夹中的项目会被返回。 深度搜索不受支持。
搜索请求
你可以使用 $search 参数将请求的结果限制为与搜索表达式匹配的邮件。 搜索字符串使用高级查询语法 (AQS) 表示。 结果按发送邮件的日期和时间排序。
备注
你最多可以通过 $search 请求得到 250 个结果。 只能对邮件使用 $search。 不支持搜索联系人和日历事件。
不能在搜索请求中使用 $filter 或 $orderby。 如果你这样做，你会收到这样的错误信息。
{
"error":
{
"code":"ErrorInvalidUrlQuery",
"message":"The query parameter 'OrderBy' is invalid."
}
}
| 属性 | 说明 |
|---|---|
| 附件 | 按标题搜索指定的附件。 |
| 密件抄送 | 搜索密件抄送字段。 |
| Body or Content | 搜索正文字段。 仅支持默认搜索。 |
| Category | 搜索类别字段。 |
| Cc | 搜索抄送字段。 |
| From | 搜索发件人字段。 |
| Has | 搜索带有附件字段。 |
| Participants | 搜索收件人、抄送和密件抄送字段。 |
| 接收时间 | 搜索接收时间字段中以 MM/DD/YYYY 表示的特定日期。 |
| Sender | 搜索发件人字段。 |
| Subject | 搜索主题字段。 |
| To | 搜索收件人字段。 |
您可以使用 $search 查询参数搜索常用字段而不指定属性。 默认搜索将搜索 Body、Sender 和 Subject 属性。 以下搜索将返回收件箱中三个默认属性中的任何一个包含 "pizza" 的所有邮件。
我们来看一些例子。 为了便于阅读，示例中的 URL 未经过 URL 编码；但是，如果您尝试使用这些示例，请确保在将它们发送到服务器之前对其进行 URL 编码。
要获得收件箱中在 From、Subject 或 Body 属性中包含单词 "Pizza" 的所有邮件，可以使用这个请求。
GET https://outlook.office.com/api/v1.0/me/messages?$search="pizza"
要获得收件箱中 Subject 属性包含单词 "Pizza" 的所有邮件，可以使用这个请求。
GET https://outlook.office.com/api/v1.0/me/messages?$search="subject:pizza"
要获得收件箱由特定人员发送的所有邮件，可以使用此请求。
GET https://outlook.office.com/api/v1.0/me/messages?$search="from:help@contoso.com"
上面的例子不包括 URL 编码，下面是经过 URL 编码并准备发送到服务器的相同示例：
GET https://outlook.office.com/api/v1.0/me/messages?$search=%22pizza%22
GET https://outlook.office.com/api/v1.0/me/messages?$search=%22subject:pizza%22
GET https://outlook.office.com/api/v1.0/me/messages?$search=%22from:help@contoso.com%22
筛选请求
你可以使用 $filter 查询参数，通过使用以下过滤器运算符来指定搜索条件。
并非所有属性都支持筛选。 只有“可筛选？”中标记为“是”的资源属性 可以使用上面对应表中的列。 如果某个属性不可筛选，则会收到一条错误消息，例如如果尝试筛选 ChangeKey 属性，将显示：
{
"error":
{
"code":"ErrorInvalidProperty",
"message":"The property 'ChangeKey' does not support filtering."
}
}
如果使用不支持的筛选方法，则会收到类似于下面的错误消息，例如对Subject 属性使用 startswith 筛选方法时，将显示：****
{
"error":
{
"code":"ErrorInvalidUrlQueryFilter",
"message":"'contains' and 'startswith' are not supported for filtering. Use Search instead."
}
}
| 运算符 | 类型 | 示例 |
|---|---|---|
| 和 | 逻辑与（用于组合多个标准） | TotalCount gt 0 and ChildFolderCount eq 0 |
| 或 | 逻辑或（用于组合多个条件） | TotalCount gt 0 or ChildFolderCount eq 0 |
| eq | 等于 | IsRead eq false |
| ne | 不等于 | Importance ne Microsoft.Exchange.Services.OData.Model.Importance'High' |
| gt | 大于 | DateTimeReceived gt 2014-09-01T00:00:00Z |
| ge | 大于或等于 | DateTimeLastModified ge 2014-09-01T00:00:00Z |
| lt | 小于 | DateTimeReceived lt 2014-09-01T00:00:00Z |
| le | 小于或等于 | DateTimeLastModified le 2014-09-01T00:00:00Z |
使用单引号 (') 分隔筛选条件中的任何字符串值。 使用 %27 对单引号进行 URL 编码。 字符串本身不区分大小写。
我们来看一些例子。 为了便于阅读，示例中的 URL 未经过 URL 编码；但是，如果您尝试使用这些示例，请确保在将它们发送到服务器之前对其进行 URL 编码。
要获取用户日历中具有特定主题的所有事件，可以筛选 Subject 属性。
GET https://outlook.office.com/api/v1.0/me/events?$filter=Subject eq 'Mega Charity Bash'
要在收件箱中获取所有未读邮件，可以筛选 IsRead 属性。
GET https://outlook.office.com/api/v1.0/me/messages?$filter=IsRead eq false
要获取收件箱中带有附件的所有邮件，可以筛选 HasAttachments 属性。
GET https://outlook.office.com/api/v1.0/me/messages?$filter=HasAttachments eq true
要获取收件箱中从 2014 年 9 月 1 日起收到的所有邮件，可以筛选 DateTimeReceived 属性。
GET https://outlook.office.com/api/v1.0/me/messages?$filter=DateTimeReceived ge 2014-09-01
要在收件箱中获取所有来自 "hr@contoso.com" 的邮件，可以筛选 Sender 属性。
GET https://outlook.office.com/api/v1.0/me/messages?$filter=From/EmailAddress/Address eq 'hr@contoso.com'
上面的例子不包括 URL 编码，下面是经过 URL 编码并准备发送到服务器的相同示例：
GET https://outlook.office.com/api/v1.0/me/events?$filter=Subject%20eq%20%27Mega%20Charity%20Bash%27
GET https://outlook.office.com/api/v1.0/me/messages?$filter=IsRead%20eq%20false
GET https://outlook.office.com/api/v1.0/me/messages?$filter=HasAttachments%20eq%20true
GET https://outlook.office.com/api/v1.0/me/messages?$filter=DateTimeReceived%20ge%202014-09-01
GET https://outlook.office.com/api/v1.0/me/messages?$filter=From/EmailAddress/Address%20eq%20%27hr@contoso.com%27
选择要返回的特定属性
你可以使用 $select 查询参数以仅指定应用程序需要的属性。
备注
获取邮件、日历和联系人项目时，请始终使用 $select 排除响应有效负载中不需要的属性以保持合适的应用程序性能。 如果不包括一个 $select 参数，将返回项目的所有属性。
以下示例获取收件箱中所有邮件的 Subject、Sender 和 DateTimeReceived 属性。
GET https://outlook.office.com/api/v1.0/me/messages?$select=Subject,Sender,DateTimeReceived
排序结果
你可以使用 $orderby 查询参数排序结果。 将此参数的值设置为属性名称，并可以指定升序（默认）或降序。 请记住，$orderby 查询参数不能与 $search 一起使用。
以下没有 URL 编码的示例将获取收件箱中的所有邮件并按** DateTimeReceived** 属性降序排列。
GET https://outlook.office.com/api/v1.0/me/messages?$orderby=DateTimeReceived desc
经 URL 编码的相同示例：
GET https://outlook.office.com/api/v1.0/me/messages?$orderby=DateTimeReceived%20desc
分页结果
默认情况下，对 Messages 或 ChildFolders 属性、集合或者 CalendarView 的 GET 请求将返回 10 个条目（最多 50 个）。 要更改此行为，可以通过使用 $top 查询参数来设置最大数量。 以下示例获取收件箱中的前五个邮件。
GET https://outlook.office.com/api/v1.0/me/messages?$top=5
如果收件箱中有超过五封邮件，则回复中会包含一个 odata.nextLink 属性。 此属性的存在表示服务器上有更多可用项目。 此属性的值是一个可用于获取下五个项目的 URI。
GET https://outlook.office.com/api/v1.0/me/messages?$top=5&$skip=5
分页是通过使用 $top 参数来指定页面大小和 $skip 参数作为页面大小的倍数。 通过增加按页面大小的 $skip 参数值，可以请求结果集中的下一页。
统计集合中的实体
可以通过使用 $count 参数获得集合中实体的数量。 您也可以筛选计数请求。
本示例获取收件箱中的邮件数量。
GET https://outlook.office.com/api/v1.0/me/messages/$count
未经 URL 编码的这个例子获取收件箱中未读邮件的数量。
GET https://outlook.office.com/api/v1.0/me/messages/$count?$filter=IsRead eq false
经 URL 编码的相同示例：
GET https://outlook.office.com/api/v1.0/me/messages/$count?$filter=IsRead%20eq%20false
综合运用
您可以组合参数来创建复杂的查询。 下面的示例按以下方式对收件箱中的邮件进行查询：
仅返回重要性设置为“高”的项目。
只返回 Subject、Sender 和 DateTimeReceived 属性。
只返回前五条消息。
备注
未使用 URL 编码，并且已添加换行符以使示例更易于阅读。
https://outlook.office.com/api/v1.0/me/messages?
$filter=Importance eq 'High'
&$select=Subject,Sender,DateTimeReceived
&$top=5
如果指定 $filter，服务器会推断结果的排序顺序。 如果同时使用 $filter 和 $orderby，必须先在 $filter中列出 $orderby的属性，然后再列出其他任何属性，且必须按照它们在 $filter 参数中的顺序列出这些属性。 以下示例显示了一个由Subject 和 Importance 属性筛选，然后按 Subject、Importance 和 Sender 属性排序的查询。
https://outlook.office.com/api/v1.0/me/messages?
$filter=Subject eq 'Good Times' AND Importance eq 'High'&
$orderby=Subject,Importance,Sender
以下是使用 URL 编码和不带换行符的相同示例。
https://outlook.office.com/api/v1.0/me/messages?$filter=Importance%20eq%20%27High%27&select=Subject,Sender,DateTimeReceived&$top=5
https://outlook.office.com/api/v1.0/me/messages?$filter=Subject%20eq%20%27Good%20Times%27%20AND%20Importance%20eq%20%27High%27&$orderby=Subject,Importance,Sender