Get and set Outlook item data in read or compose forms

apps for Office

Learn about the few ways to get or set data on an appointment or message in an Exchange mailbox, taking into account whether the user is viewing or composing that item. You can use item-level properties in the JavaScript API for Office, Exchange Server callback tokens, Exchange Web Services.

Last modified: November 14, 2014

Applies to: Exchange Online | Exchange Server 2013 SP1 | Outlook 2013 RT | Outlook 2013 SP1 | Outlook for Mac for Office 365 | Outlook Web App | OWA for Devices

   Office.js: v1.1

   Apps for Office manifests schema: v1.1

Note Note

"Outlook" in this article refers to Outlook for Windows, Outlook for Mac, Outlook RT, OWA for Devices (OWA for Android phones, OWA for iPad, OWA for iPhone), and Outlook Web App. At this point, Outlook for Mac supports JavaScript API for Office in only Outlook read mode, and can activate mail apps that reference office.js version 1.0 or 1.1 and use apps for Office schema version 1.0.

In this article
Properties available in read and compose forms
Using Exchange Server callback tokens from a read app
Accessing Exchange Web Services from a read or compose app
Additional resources

Starting in version 1.1 of the apps for Office manifests schema, Outlook can activate mail apps when the user is viewing or composing an item. Depending on whether a mail app is activated in a read or compose form, the properties that are available to the app on the item differ as well. For example, the dateTimeCreated and dateTimeModified properties are defined only for an item that has already been sent (item is subsequently viewed in a read form) but not when the item is being created (in a compose form). Another example is the bcc property which is only meaningful when a message is being authored (in a compose form), and is not accessible to the user in a read form.

Table 1 shows the item-level properties in the JavaScript API for Office that are available in each of read and compose modes of mail apps. Typically, those properties available in read forms are read-only, and those available in compose forms are read/write, with the exception of the itemId* and conversationId* properties, which are available read-only regardless. For the remaining item-level properties available in compose forms, because the mail app and user can possibly be reading or writing the same property at the same time, the methods to get or set them in compose mode are asynchronous, and hence the type of the objects returned by these properties are also different in compose forms than in read forms. For more information about using asynchronous methods to get or set item-level properties in compose mode, see Get and set item data in a compose form in Outlook.

Table 1. Item properties available in compose and read forms

Object

Property

Property type in read forms

Property type in compose forms

Item

dateTimeCreated

JavaScript Date object

Property not available

dateTimeModified

JavaScript Date object

Property not available

itemClass

String

Property not available

itemId

Integer*

Integer*

itemType

String in ItemType enumeration

Property not available

Appointment

attachments

AttachmentDetails

Property not available

body

Property not available

Body

end

JavaScript Date object

Time

location

String

Location

normalizedSubject

String

Property not available

optionalAttendees

EmailAddressDetails

Recipients

organizer

EmailAddressDetails

Property not available

requiredAttendees

EmailAddressDetails

Recipients

resources

String

Property not available

start

JavaScript Date object

Time

subject

String

Subject

Message

attachments

AttachmentDetails

Property not available

bcc

Property not available

Recipients

body

Property not available

Body

cc

EmailAddressDetails

Recipients

conversationId

Integer*

Integer*

from

EmailAddressDetails

Property not available

internetMessageId

Integer

Property not available

normalizedSubject

String

Property not available

sender

EmailAddressDetails

Property not available

subject

String

Subject

to

EmailAddressDetails

Recipients

If your mail app is to be activated in read forms, you can get an Exchange callback token and let server-side code to use the Exchange Web Services (EWS) operation, GetItem, to get properties of an item selected on the user’s mailbox. By specifying the ReadItem permission in the app manifest, you can use the Mailbox.getCallbackTokenAsync method to get an Exchange callback token, the Mailbox.ewsUrl property to get the URL of the EWS endpoint for the user’s mailbox, and Item.itemId to get the EWS ID for the selected item. You can then pass the callback token, EWS endpoint URL, and the EWS item ID to server-side code to access the GetItem operation, to get more properties of the item.

You can also use the Mailbox.makeEwsRequestAsync method to access the Exchange Web Services (EWS) operations, GetItem and UpdateItem, to get and set many properties of a specified item. This method and the EWS operations are available to mail apps regardless of whether the app has been activated in a read or compose form, as long as you specify the ReadWriteMailbox permission in the app manifest. For more information in using makeEwsRequestAsync to access EWS operations, see Call web services from a mail app for Outlook.

Show:
© 2014 Microsoft