Edit

Get and set Outlook item data in read or compose forms

  • Article

Starting in version 1.1 of the Office Add-ins manifests schema, Outlook can activate add-ins when the user is viewing or composing an item. Depending on whether an add-in is activated in a read or compose form, the properties that are available to the add-in 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.

Item properties available in compose and read forms

Table 1 shows the item-level properties in the Office JavaScript API that are available in each mode (read and compose) of mail add-ins. 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, conversationId, and itemType properties, which are always read-only regardless.

For the remaining item-level properties available in compose forms, because the add-in 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 may also be 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


Item type Property Property type in read forms Property type in compose forms
Appointments and messages dateTimeCreated JavaScript Date object Property not available
Appointments and messages dateTimeModified JavaScript Date object Property not available
Appointments and messages itemClass String Property not available
Appointments and messages itemId String Property not available
Appointments and messages itemType String in ItemType enumeration String in ItemType enumeration (read-only)
Appointments and messages attachments AttachmentDetails Property not available
Appointments and messages body Body Body
Appointments and messages normalizedSubject String Property not available
Appointments and messages subject String Subject
Appointments end JavaScript Date object Time
Appointments location String Location
Appointments optionalAttendees EmailAddressDetails Recipients
Appointments organizer EmailAddressDetails Organizer
Appointments requiredAttendees EmailAddressDetails Recipients
Appointments start JavaScript Date object Time
Messages bcc Property not available Recipients
Messages cc EmailAddressDetails Recipients
Messages conversationId String String (read-only)
Messages from EmailAddressDetails From
Messages internetMessageId Integer Property not available
Messages sender EmailAddressDetails Property not available
Messages to EmailAddressDetails Recipients

Use Exchange Server callback tokens from a read add-in

If your Outlook add-in is activated in read forms, you can get an Exchange callback token. This token can be used in server-side code to access the full item via Exchange Web Services (EWS).

By specifying the read item permission in the add-in 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.

Access EWS from a read or compose add-in

You can also use the mailbox.makeEwsRequestAsync method to access the Exchange Web Services (EWS) operations GetItem and UpdateItem directly from the add-in. You can use these operations to get and set many properties of a specified item. This method is available to Outlook add-ins regardless of whether the add-in has been activated in a read or compose form, as long as you specify the read/write mailbox permission in the add-in manifest. For more information about the read/write mailbox permission, see Understanding Outlook add-in permissions

For more information about using makeEwsRequestAsync to access EWS operations, see Call web services from an Outlook add-in.

See also