Get and set Outlook item data in read or compose forms
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.
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 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
|Item type||Property||Property type in read forms||Property type in compose forms|
|Appointments and messages||itemClass||String||Property not available|
|Appointments and messages||itemId||String||Property not available|
|Appointments and messages||itemType||String in ItemType enumeration||Property not available|
|Appointments and messages||attachments||AttachmentDetails||Property not available|
|Appointments and messages||body||Body||Body|
|Appointments and messages||normalizedSubject||String||Property not available|
|Appointments||organizer||EmailAddressDetails||Property not available|
|Appointments||resources||String||Property not available|
|Appointments and messages||subject||String||Subject|
|Messages||bcc||Property not available||Recipients|
|Messages||conversationId||String||String (read only)|
|Messages||from||EmailAddressDetails||Property not available|
|Messages||internetMessageId||Integer||Property not available|
|Messages||sender||EmailAddressDetails||Property not available|
Using 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 ReadItem 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.
Accessing 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 ReadWriteMailbox permission in the add-in manifest.
For more information about using makeEwsRequestAsync to access EWS operations, see Call web services from an Outlook Add-in.