JavaScript API for Office Outlook Add-in

上一篇文章 Office Add-in Model 为 Outlook Mail Add-in 提供的 JavaScript API 介绍，简单地在表格中列出了所有的 Object 定义，但是个人感觉表格仅适合列一些简单的内容，太多的话就不再直观了。本文沿着上篇的骨骼，对每个 Object 及 API 进行了扩展，多数的东西都来自于官方文档（尽量把分散在各地的补充说明归纳起来），我写这篇博文的目的并不是想把所有的 Object、方法、属性都涵盖，更多地是从 agile 开发的角度出发，这样我们在开发 Outlook Mail Add-in 的时候就能更快地找到合适的 API 及其定义了。

本文将从 Object Model 的角度更详细的罗列出 Mail Add-in 中可以访问的 Object 以及它所提供的方法和属性。

Office

Office Object 表示 Add-in 的一个实例, 它是调用其它API相关的 Object (如Context等) 的入口。

代码示例（本文中所有代码示例如无特殊注明，均为 JavaScript 代码）：

Office

Office.js版本：此 Object 在 Office.js v1.0 中引入，最后一次更新是在 v1.1中。

在哪些 Outlook 模式中可用：撰写邮件、读邮件 (Compose or read)

最低权限要求： N/A

官方文档：https://msdn.microsoft.com/en-us/library/office/fp142234.aspx

Office.context

Context Object 表示 Add-in 的运行时环境信息，并提供调用关键 Object（如 Mailbox) 上 API 的入口

代码示例：

Office.context

Office.js版本：此 Object 在 Office.js v1.0 中引入，后续无更新。

在哪些 Outlook 模式中可用：撰写邮件、读邮件 (Compose or read)

最低权限要求： N/A

官方文档： https://msdn.microsoft.com/EN-US/library/office/fp161104.aspx

Office.context.roamingSettings

RoamingSettings Object 用来存储per user，per add-in的custom settings。RoamingSettings 中的值只能被创建该值的用户所访问（ 这也是 RoamingSettings 和下文提到的 Office.context.mailbox.item.loadCustomPropertiesAsync()不同的地方），并且只能在被创建该值的 add-in 中访问到。Setting 的key是字符串类型的， value 的类型则可以是string、number、boolean、null、object或者array。

RoamingSettings Object是作为 Context 对象的一部分自动加载的，当 add-in 被激活后，便可以通过访问 roamingSettings 来获得或设置其中的值。

代码示例：

var _settings;

var _customerName;

// The initialize function is required for all add-ins.

Office.initialize = function () {

    // Checks for the DOM to load using the jQuery ready function.

    $(document).ready(function () {

        // After the DOM is loaded, app-specific code can run

        // Initialize instance variables to access API objects.

        _settings = Office.context.roamingSettings;

        // Set new settings

        _settings.set("customerName", "Paul");

        _settings.saveAsync(saveMyAppSettingsCallback);

        // Load existing settings.

        _customerName = _settings.get("customerName");

        // Remove an existing setting.

        _settings.remove("customerName");

        _settings.saveAsync(saveMyAppSettingsCallback);

    });

}

// Callback method after saving custom application roaming settings.

function saveMyAppSettingsCallback(asyncResult) {

    if (asyncResult.status == Office.AsyncResultStatus.Failed) {

        // Handle the failure.

    }

}

Office.js版本：此 Object 在 Office.js v1.0 中引入，后续无更新。

哪些 Outlook 模式中可用：撰写邮件、读邮件 (Compose or read)

最低权限要求： Restricted

官方文档：https://msdn.microsoft.com/en-us/library/office/jj220079.aspx

一些实例：Persist metadata for the same mailbox by using roaming settings

Office.context.mailbox

Mailbox Object 是 Office Add-in Object Model 的入口，所有与邮件甚至邮箱用户信息相关的操作都需要通过 Office.context.mailbox 来调用。

代码示例：

Office.context.mailbox

Office.js版本：此 Object 在 Office.js v1.0 中引入，后续无更新。

在哪些 Outlook 模式中可用：撰写邮件、读邮件 (Compose or read)

最低权限要求： ReadWriteMailbox, but some members accessible with lesser permissions

官方文档：https://msdn.microsoft.com/EN-US/library/office/fp142162.aspx

Office.context.mailbox.userProfile

UserProfile Object 表示当前邮箱登录用户的信息, 它封装了用户的显示名称（Display Name）、邮箱地址、用户本地时区。

属性(Property)	类型	描述
displayName	字符串(string)	用于显示的用户名.
emailAddress	字符串(string)	SMTP email address.
timeZone	字符串(string)	Host 当前 add-in 的应用程序（ Outlook richlient，或 OWA 等）中设置的时区信息。

代码示例：

// The initialize function is required for all add-ins.

Office.initialize = function () {

    // Checks for the DOM to load using the jQuery ready function.

    $(document).ready(function () {

        // After the DOM is loaded, addin-specific code can run.

        var userProfile = Office.context.mailbox.userProfile;

        // The user name to use for display.

        var name = userProfile.displayName;

        // The user's SMTP email address.

        var emailAdrress = userProfile.emailAddress;

        // The user's local time zone

        var timeZone = userProfile.timeZone;

    });

}

Office.js版本：此 Object 在 Office.js v1.0 中引入，后续无更新。

在哪些 Outlook 模式中可用：撰写邮件、读邮件 (Compose or read)

最低权限要求： ReadItem

官方文档：https://msdn.microsoft.com/en-us/library/office/fp161126.aspx

Office.context.mailbox.item

Item Object 表示 host 并激活当前 Add-in 的邮件信息条目或者约会条目。

Item Object 包含的方法和属性分别有：

方法（Method）	Outlook 模式	描述	在什么版本引入
loadCustomPropertiesAsync	撰写、读邮件(Compose or read)	为某个特定的邮件条目提供自定义的属性集合，这些属性集合可以自由地添加或删除，他们保存在邮件服务器上。适用于存储一些针对于邮件条目的相关信息（可理解为邮件的 Property Bag）。	Version 1.0
getSelectedDataAsync	撰写、读邮件(Compose or read)	获得邮件主题或邮件正文中被选中的数据。	Version 1.2
setSelectedDataAsync	撰写、读邮件(Compose or read)	插入数据到邮件主题或正文中的当前选中区域中。	Version 1.2
close	撰写邮件(Compose)	关闭正在编辑的邮件，关于如何处理未保存的邮件，请参考该函数页面的具体描述。	Version 1.3
saveAsync	撰写邮件(Compose)	保存当前条目到草稿箱中。官网上说读邮件(Read)模式下也可用，但是个人理解，这个函数应该只是在撰写邮件模式下才可能调用。	Version 1.3

属性（Property）	Outlook 模式	描述	在什么版本引入
dateTimeCreated	读邮件(Read)	获得当前邮件条目创建的日期和时间。	Version 1.0
dateTimeModified	读邮件(Read)	获得当前邮件条目最后被修改的日期和时间。	Version 1.0
itemClass	读邮件(Read)	获得当前邮件条目的类别。对于邮件约会条目，只有一个类别 IPM.Appointment；对于邮件信息条目，有如下几种类别： IPM.Note IPM.Schedule.Meeting.Request IPM.Schedule.Meeting.Neg IPM.Schedule.Meeting.Pos IPM.Schedule.Meeting.Tent IPM.Schedule.Meeting.Canceled	Version 1.0
itemId	读邮件(Read)	Gets the unique identifier for the item.	Version 1.0
itemType	撰写、读邮件(Compose or read)	Gets the type of the item.	Version 1.0

Item Object 是一个 base Object，其他的“表示特定条目的Object”（如 Appointment 和 Message ）都是它的扩展，可以根据 itemType 属性来判断是 Appointment 还是 Message。

Item type	Object
Meeting	Appointment
Message	Message

关于 Appointment 和 Message，以及 MettingRequest Object 它们分别特有的方法、属性，可以参考如下链接，接下来一一罗列。

Appointment Object 表示当前约会条目

其包含的方法与属性如下：

属性名	Outlook 模式	描述	从什么版本开始引入
attachments	读邮件（Read）	获得邮件会议或约会的附件信息，下文也有针对 Office.context.mailbox.item.attachments 的介绍。	Version 1.0
body	撰写邮件（Compose）	Gets a Body object that provides access the body text of the appointment.	Version 1.1
end	Compose or read	Gets a Date object that contains or a Time object that provides access to the date and time that the appointment is to end.	Version 1.0
location	Compose or read	Gets a string that contains or a Location object that provides access to the location of the appointment.	Version 1.0
normalizedSubject	Read	Gets the subject of the appointment, with all prefixes removed (including "RE:" and "FWD:").	Version 1.0
notificationMessages	Compose or read	Gets the notification messages for an appointment.	Version 1.3
optionalAttendees	Compose or read	Gets an EmailAddressDetails object that contains or a Recipients object that provides access to optional attendees.	Version 1.0
organizer	Read	Gets an EmailAddressDetails object that contains the organizer of the appointment.	Version 1.0
requiredAttendees	Compose or read	Gets an EmailAddressDetails object that contains or a Recipients object that provides access to required attendees.	Version 1.0
resources	Read	Gets an EmailAddressDetails object that contains a list of resources required for the meeting.	Version 1.0
start	Compose or read	Gets a Date object that contains or a Time object that provides access to the date and time that the appointment is to begin.	Version 1.0
subject	Compose or read	Gets a string that contains or a Subject object that provides access to the complete subject of the appointment with all prefixes.	Version 1.0

Method name	Outlook mode	Description	Introduced in
addFileAttachmentAsync	Compose	Adds files as attachments to the appointment.	Version 1.1
addItemAttachmentAsync displayReplyAllForm displayReplyForm	Compose Read Read	Adds mailbox items as attachments to the appointment. Displays a reply form including organizer and attendees. Displays a reply form including only the organizer.	Version 1.1 Version 1.0 Version 1.0
getEntities	Read	Returns all entities recognized in the appointment.	Version 1.0
getEntitiesByType	Read	Returns all entities of the specified type recognized in the appointment.	Version 1.0
getFilteredEntitiesByName	Read	Returns all matches recognized in the appointment that meet the requirements of the named filter.	Version 1.0
getRegExMatches	Read	Returns all regular expression matches recognized in the appointment.	Version 1.0
getRegExMatchesByName	Read	Returns all regular expression matches recognized in the appointment using the named regular expression.	Version 1.0
removeAttachmentAsync	Compose	Removes a specified or all attachments from the appointment.	Version 1.1

Message Object 表示当前邮件信息条目（区别于会议或约会）

Property name	Outlook mode	Description	Introduced in
attachments	Compose	Gets an array of attachments for the message.	Version 1.0
body	Compose	Gets a Body object that provides access the body text of the message.	Version 1.1
bcc	Compose	Gets a Recipients object that provides access to each recipient on the Bcc line of the message.	Version 1.1
cc	Compose or read	Gets a collection EmailAddressDetails object that contains or a Recipients object that provides access to each recipient on the Cc line of the message.	Version 1.0
conversationId	Compose or read	Gets the identifier for the conversation that the message is associated with.	Version 1.0
from	Read	Gets an EmailAddressDetails object for the message sender.	Version 1.0
internetMessageId	Read	Gets the unique Internet message identifier for the message.	Version 1.0
normalizedSubject	Read	Gets the subject of the message, with all prefixes removed (including "RE:" and "FWD:").	Version 1.0
notificationMessages	Compose or read	Gets the notification messages for a message.	Version 1.3
sender	Read	Gets an EmailAddressDetails object for the message sender.	Version 1.0
subject	Compose or read	Gets a string that contains or a Subject object that provides access to the complete subject of the message with all prefixes.	Version 1.0
to	Compose or read	Gets a collection EmailAddressDetails object that contains or a Recipients object that provides access to each recipient on the To line of the message.	Version 1.0

Method name	Outlook mode	Description	Introduced in
addFileAttachmentAsync	Compose	Adds files as attachments to the message.	Version 1.1
addItemAttachmentAsync displayReplyAllForm displayReplyForm	Compose Read Read	Adds mailbox items as attachments to the message. Displays a reply form that includes the sender and all recipients of the selected message. Displays a reply form that includes only the sender of the selected message.	Version 1.1 Version 1.0 Version 1.0
getEntities	Read	Returns all entities found in the message.	Version 1.0
getEntitiesByType	Read	Returns all entities of the specified type found in the message.	Version 1.0
getFilteredEntitiesByName	Read	Returns all matches recognized in the message that meet the requirements of the named filter.	Version 1.0
getRegExMatches	Read	Returns all regular expression matches found in the message.	Version 1.0
getRegExMatchesByName	Read	Returns all regular expression matches recognized in the message using the named regular expression.	Version 1.0
removeAttachmentAsync	Compose	Removes a specified or all attachments from the message.	Version 1.1

MeetingRequest Object 扩展了 Message Object，表示一个会议邀请

（The MeetingRequest object is returned as the item property of the Mailbox object. The MeetingRequest object extends the Message object. Represents a request to attend a meeting.）

Property name	Outlook mode	Description	Introduced in
end	Read	Gets the time that the meeting is to end.	Version 1.0
location	Read	Gets the location of the meeting.	Version 1.0
optionalAttendees	Read	Gets the list of optional attendees for the meeting.	Version 1.0
requiredAttendees	Read	Gets the list of required attendees for the meeting.	Version 1.0
resources	Read	Gets the list of resources needed for the meeting.	Version 1.0
start	Read	Gets the time that the meeting is to start.	Version 1.0

Office.context.mailbox.item 的返回值取决于当前查看的邮件条目类型。例如，如果当前邮件条目是信息条目，返回值为一个Message Object；如果是一个约会条目，返回值为一个 Appointment Object。

注意: 下文中介绍的 Office.context.mailbox.item 的子 Object 或方法，有些是与当前邮件类型相关的。例如同样是Office.context.mailbox.item，如果当前邮件条目为约会条目，则它有 requiredAttendees 属性；而如果是邮件信息条目，则它会有 cc、to 等属性。

代码示例：

// The initialize function is required for all add-ins.

Office.initialize = function () {

    /* Checks for the DOM to load using the jQuery ready function. */

    $(document).ready(function () {

        // After the DOM is loaded, app-specific code can run.

        var item = Office.context.mailbox.item;

        var subject = item.subject;

        // Continue with processing the subject of the current item, which can be a message or appointment.

    });

}

Office.js版本：此 Object 在 Office.js v1.0 中引入，最后一次更新是在 v1.3中。

在哪些 Outlook 模式中可用：撰写邮件、读邮件 (Compose or read)

最低权限要求： ReadItem

官方文档：

Item object：https://msdn.microsoft.com/EN-US/library/office/fp142177.aspx

Message Object： https://msdn.microsoft.com/EN-US/library/office/fp161175.aspx

MeetingRequest Object：https://msdn.microsoft.com/EN-US/library/office/fp142237.aspx?f=255&MSPPError=-2147217396

Appointment Object： https://msdn.microsoft.com/EN-US/library/office/fp160964.aspx

Office.context.mailbox.item.attachments

AttachmentDetails Object 表示当前邮件条目中包含的附件信息，它封装了如下属性：

属性(Property)	类型	描述
attachmentType	Office.MailboxEnums.AttachmentType	Gets one of the AttachmentType enumeration values that indicates whether the attachment is an Exchange item or a file.
contentType	字符串(string)	Gets the MIME content type of the attachment.
id	字符串(string)	Gets the Exchange Web Services (EWS) attachment identifier for the attachment.
isInline	布尔(boolean)	Gets a value that indicates whether the attachment is an inline attachment. The isInline property indicates whether an attachment, such as an embedded image, should be displayed in the item.
name	字符串(string)	Gets the name of the attachment.
size	整型(integer)	Gets the size of the attachment in bytes. An integer that contains the size of the attachment in bytes.

其中 Office.MailboxEnums.AttachmentType 是个枚举类型，可取的值包括：

Enumeration	值	描述
Office.MailboxEnums.AttachmentType.File	"file"	The attachment is a file.
Office.MailboxEnums.AttachmentType.Item	"item"	The attachment is an Exchange item.

代码示例：

// An array of AttachmentDetail objects is returned as the attachments property of an Item,

// Appointment, or Message objects.

Office.context.mailbox.item.attachments

Office.js版本：此 Object 在 Office.js v1.0 中引入，后续无更新。

在哪些 Outlook 模式中可用：读邮件 (Read)

最低权限要求： ReadItem

官方文档：https://msdn.microsoft.com/EN-US/library/office/jj984592.aspx

Office.context.mailbox.item.body

Body Object 表示当前邮件信息或约会条目的正文内容，它提供了一些方法来为邮件信息或约会条目增加/更新正文内容，如下表所示。

方法（Method）	描述
getAsync	以指定的格式（"html" 或 "text" ）获得当前用户在邮件主题或正文中选择的数据，该API 从 Office.js v1.3 版本引入，在撰写邮件、读邮件(Compose or Read) 两种模式下均可调用。
getTypeAsync	获得邮件正文内容格式，取值可以为 "html" 或 "text"。 V1.1 中引入。
prependAsync	在邮件正文的前面添加指定的内容，This method was introduced in version 1.1.
setAsync	利用指定的内容替换掉邮件原有内容，在 v1.3 中引入。
setSelectedDataAsync	利用指定的内容替换掉正文中选中部分，v1.1 引入。

代码示例：

Office.context.mailbox.item.body

TODO: 添加实例

Office.js版本：此 Object 在 Office.js v1.1 中引入，最后一次更新是在 v1.3中。

在哪些 Outlook 模式中可用：撰写邮件(Compose)

最低权限要求：ReadItem

官方文档：https://msdn.microsoft.com/EN-US/library/office/dn482486.aspx

Office.context.mailbox.item.subject

Subject Object 表示邮件信息或会议的主题。

Compose 模式下：Office.context.mailbox.item.subject 返回邮件会议或邮件信息的Subject Object，该 Object 提供用于获得或设置邮件主题的方法：

方法（Method）	描述
getAsync	获得邮件信息或约会的主题。
setAsync	设置邮件信息或约会的主题，overrides 原有的主题，但是原来的“转发”、“Fwd：”、“Re：”将会保留。

Read 模式下：Office.context.mailbox.item.subject 返回邮件会议或者邮件信息的主题（字符串）。

代码示例：

Office.initialize = function () {

    // Checks for the DOM to load using the jQuery ready function.

    $(document).ready(function () {

        // After the DOM is loaded, app-specific code can run.

        var item = Office.context.mailbox.item;

        // Get the subject of the item being composed.

        item.subject.getAsync(

            function (asyncResult) {

                if (asyncResult.status == Office.AsyncResultStatus.Failed){

                    console.write(asyncResult.error.message);

                }

                else {

                    // Successfully got the subject, display it.

                    console.write('The subject is: ' + asyncResult.value);

                }

            }

        );

        // Set the subject of the item that the user is composing.

        var today = new Date();

        // Customize the subject with today's date.

        var subject = 'Summary for ' + today.toLocaleDateString();

        item.subject.setAsync(

            subject,

            { asyncContext: { var1: 1, var2: 2 } },

            function (asyncResult) {

                if (asyncResult.status == Office.AsyncResultStatus.Failed){

                    console.write(asyncResult.error.message);

                }

                else {

                    // Successfully set the subject.

                    // Do whatever appropriate for your scenario

                    // using the arguments var1 and var2 as applicable.

                }

            }

        );

    });// end $(document).ready

}

Office.js版本：此 Object 在 Office.js v1.1 中引入。

哪些 Outlook 模式中可用：撰写邮件、读邮件 (Compose or read)

最低权限要求： ReadItem

官方文档：https://msdn.microsoft.com/en-us/library/office/dn482528.aspx

Office.context.mailbox.item.start/end

Time Object 表示邮件约会的开始或结束时间，Office.context.mailbox.item.start 和 Office.context.mailbox.item.end 均是这种类型的 Object。该对象仅仅适用于邮件会议或约会，因为只有会议才有开始或结束时间，因此只有 Appointment 才有 start 或 end 属性（ Message 和 MeetingRequest 对象都没有这些属性）。

Compose 模式下：Office.context.mailbox.item.start/end 返回一个Time object，它提供了方法用来获取或设置会议起（或止）的时间：

方法（Method）	描述
getAsync	Gets the value of a start or end time
setAsync	Sets the value of a start or end time。参数是一个表示 UTC 时间的 Date-Tme Object，可以利用 Mailbox.convertToUtcClientTime 获得相应的 UTC 时间

Read 模式下：Office.context.mailbox.item.start（或end）返回一个 JavaScript Date object，表示会议的起（或止）的时间。

代码示例：

Office.initialize = function () {

    // Checks for the DOM to load using the jQuery ready function.

    $(document).ready(function () {

        // After the DOM is loaded, app-specific code can run.

        var item = Office.context.mailbox.item;

        // Get the start time of the item being composed.

        item.start.getAsync(

            function (asyncResult) {

                if (asyncResult.status == Office.AsyncResultStatus.Failed){

                    console.write(asyncResult.error.message);

                }

                else {

                    // Successfully got the start time, display it, first in UTC and

                    // then convert the Date object to local time and display that.

                    console.write ('The start time in UTC is: ' + asyncResult.value.toString());

                    console.write ('The start time in local time is: ' + asyncResult.value.toLocaleString());

                }

            }

        );

        // Set the start time of the item being composed.

        var startDate = new Date("September 27, 2012 12:30:00");

        item.start.setAsync(

            startDate,

            { asyncContext: { var1: 1, var2: 2 } },

            function (asyncResult) {

                if (asyncResult.status == Office.AsyncResultStatus.Failed){

                    console.write(asyncResult.error.message);

                }

                else {

                    // Successfully set the start time.

                    // Do whatever appropriate for your scenario

                    // using the arguments var1 and var2 as applicable.

                }

            }

        );

    });// end $(document).ready

}

Office.js版本：此 Object 在 Office.js v1.1 中引入。

哪些 Outlook 模式中可用：撰写邮件会议或约会（Compose）、读邮件会议或约会（Read）

最低权限要求： ReadItem

官方文档：https://msdn.microsoft.com/en-us/library/office/dn482538.aspx

Office.context.mailbox.item.location

Location Object 表示邮件会议或约会中的地点，它提供了方法来获取并设置会议地址，该对象仅仅适用于邮件会议或约会，因为只有邮件会议，也即 Appointment Object 才有这个属性。

Compose 模式下：Office.context.mailbox.item.location 返回一个 Location object，它提供了方法用来获取或设置会议的地址：

方法（Method）	描述
getAsync	Gets the location of an appointment.
setAsync	Sets the location of an appointment.

Read 模式下：Office.context.mailbox.item.location 返回一个表示会议地点的字符串。

代码示例：

Office.initialize = function () {

    // Checks for the DOM to load using the jQuery ready function.

    $(document).ready(function () {

        // After the DOM is loaded, app-specific code can run.

        var item = Office.context.mailbox.item;

        // Get the location of the item that the user is composing.

        item.location.getAsync(

            function (asyncResult) {

                if (asyncResult.status == Office.AsyncResultStatus.Failed){

                    console.write(asyncResult.error.message);

                }

                else {

                    // Successfully got the location, display it.

                    console.write ('The location is: ' + asyncResult.value);

                }

            }

        );

        // Set the location of the item that the user is composing.

        item.location.setAsync(

            'Conference room A',

            { asyncContext: { var1: 1, var2: 2 } },

            function (asyncResult) {

                if (asyncResult.status == Office.AsyncResultStatus.Failed){

                    console.write(asyncResult.error.message);

                }

                else {

                    // Successfully set the location.

                    // Do whatever appropriate for your scenario

                    // using the arguments var1 and var2 as applicable.

                }

            }

        );

    });// end $(document).ready

}

Office.js版本：此 Object 在 Office.js v1.1 中引入。

哪些 Outlook 模式中可用：撰写邮件、读邮件 (Compose or Read)

最低权限要求： ReadItem

官方文档：https://msdn.microsoft.com/EN-US/library/office/dn482502.aspx

Recipients Object

Recipients Object提供了方法获取并设置邮件或约会的收件人。

对于 Message Object （即邮件信息条目），它的如下三个属性均是 Recipients 类型的 Object。 Office.context.mailbox.item.to，Office.context.mailbox.item.cc，Office.context.mailbox.item.bcc
对于 Appointment Object（即邮件约会条目），它的如下三个属性均是 Recipients 类型的 Object。 Office.context.mailbox.item.requiredAttendees， Office.context.mailbox.item.optionalAttendees， Office.context.mailbox.item.resources

Recipients Object 提供的方法有：

方法（Method）	描述
addAsync	Adds recipients to the item.
getAsync	Gets the recipients of an item.
setAsync	Sets the recipients of an item.

代码示例：

Office.initialize = function () {

    // Checks for the DOM to load using the jQuery ready function.

    $(document).ready(function () {

        // After the DOM is loaded, app-specific code can run.

        var item = Office.context.mailbox.item;

        // Get the email addresses of all the recipients of the composed item.

        // Local objects to point to recipients of either

        // the appointment or message that is being composed.

        // bccRecipients applies to only messages, not appointments.

        var toRecipients, ccRecipients, bccRecipients;

        // Verify if the composed item is an appointment or message.

        if (item.itemType == Office.MailboxEnums.ItemType.Appointment) {

            toRecipients = item.requiredAttendees;

            ccRecipients = item.optionalAttendees;

        }

        else { // For Message Object.

            toRecipients = item.to;

            ccRecipients = item.cc;

            bccRecipients = item.bcc;

        }

        // Use asynchronous method getAsync to get each type of recipients

        // of the composed item. Each time, this example passes an anonymous

        // callback function that doesn't take any parameters.

        toRecipients.getAsync(function (asyncResult) {

            if (asyncResult.status == Office.AsyncResultStatus.Failed){

                console.write(asyncResult.error.message);

            }

            else {

                // Async call to get to-recipients of the item completed.

                // Display the email addresses of the to-recipients.

                console.write ('To-recipients of the item:');

            }

        }); // End getAsync for to-recipients.

        // Get any cc-recipients.

        ccRecipients.getAsync(function (asyncResult) {

            if (asyncResult.status == Office.AsyncResultStatus.Failed){

                console.write(asyncResult.error.message);

            }

            else {

                // Async call to get cc-recipients of the item completed.

                // Display the email addresses of the cc-recipients.

                console.write ('Cc-recipients of the item:');

            }

        }); // End getAsync for cc-recipients.

        // If the item has the bcc field, i.e., item is message,

        // get any bcc-recipients.

        if (bccRecipients) {

            bccRecipients.getAsync(function (asyncResult) {

                if (asyncResult.status == Office.AsyncResultStatus.Failed){

                    console.write(asyncResult.error.message);

                }

            else {

                // Async call to get bcc-recipients of the item completed.

                // Display the email addresses of the bcc-recipients.

                console.write ('Bcc-recipients of the item:');

            }

            }); // End getAsync for bcc-recipients.

        }

    });// end $(document).ready

}

Office.js版本：此 Object 在 Office.js v1.1。

哪些 Outlook 模式中可用：撰写邮件(Compose)

最低权限要求： ReadItem

官方文档：https://msdn.microsoft.com/en-us/library/office/dn482517.aspx

Entities

Exchange Server 可以根据邮件内容检测出地理位置、邮箱地址、联系人信息、任务分配信息等， Entity 的识别依赖于自然语言的识别，而后者又要基于大量数据做机器学习才能做到，总的来说，entity的识别结果并不完全准确，识别的成功率很大程度上依赖于邮件中包含的特定语境信息。

我们可以利用 Office.context.mailbox.item.getEntities()/getEntitiesByType()/getFilteredEntitiesByName() 取出来这样一组信息集合，集合中包括如下几种类型的属性：

属性名	Outlook 模式	描述	从什么版本开始引入
addresses	读邮件（Read）	Exchange Server 2013 服务在邮件条目中检测到的一条或多条地理位置信息；如果不存在，返回 null。	Version 1.0
contacts	读邮件（Read）	Exchange Server 2013 服务在邮件条目中检测到的一条或多条联系人信息；如果不存在，返回 null。	Version 1.0
emailAddresses	读邮件（Read）	Exchange Server 2013 服务在邮件条目中检测到的一条或多条 SMTP 邮箱信息；如果不存在，返回 null。	Version 1.0
meetingSuggestions	读邮件（Read）	Exchange Server 2013 服务在邮件条目中检测到的一条或多条“会议建议”信息；如果不存在，返回 null。	Version 1.0
phoneNumbers	读邮件（Read）	Exchange Server 2013 服务在邮件条目中检测到的一条或多条电话号码；如果不存在，返回 null。	Version 1.0
taskSuggestions	读邮件（Read）	Exchange Server 2013 服务在邮件条目中检测到的一条或多条“任务建议”；如果不存在，返回 null。	Version 1.0
urls	读邮件（Read）	Exchange Server 2013 服务在邮件条目中检测到的一条或多条 Internet Urls；如果不存在，返回 null。	Version 1.0

代码示例：

Office.context.mailbox.item.getEntities().taskSuggestions;

Office.context.mailbox.item.getEntitiesByType(EntityType.TaskSuggestion).taskSuggestions;

Office.context.mailbox.item.getEntities().emailAddresses；

Office.js版本：此 Object 在 Office.js v1.0 中引入。

哪些 Outlook 模式中可用：读邮件 (ead)

最低权限要求： ReadItem 或 Restricted，具体请查看每个 Entity 链接中的定义。

官方文档：https://msdn.microsoft.com/EN-US/library/office/fp160984.aspx

Office.context.mailbox.diagnostics

Diagnostics Object 提供用于 troubleshooting 的信息， Office.context.mailbox.diagnostics 的主要属性如下：

Property name	Outlook mode	Description	Introduced in
hostName	Compose or read	Gets a string that represents the name of the host application for the mail app.	Version 1.0
hostVersion	Compose or read	Gets a string that represents the version of either the host application or the Exchange Server.	Version 1.0
OWAView	Compose or read	Gets a string that represents the current view of Outlook Web App.	Version 1.0

代码示例：

Office.context.mailbox.diagnostics.hostName

Office.js版本：此 Object 在 Office.js v1.0 中引入。

哪些 Outlook 模式中可用：撰写邮件、读邮件 (Compose or read)

最低权限要求： ReadItem

官方文档：https://msdn.microsoft.com/EN-US/library/office/jj715287.aspx