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.
Item properties available in compose and read forms
The following table 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.
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
Important
Legacy Exchange user identity tokens and callback tokens will be turned off for all Exchange Online tenants in October 2024 as part of Microsoft’s Secure Future Initiative, which gives organizations the tools needed to respond to the current threat landscape. Exchange user identity tokens will still work for Exchange on-premises. Nested app authentication is the recommended approach for tokens going forward. For more information, see our blog post about nested app authentication and legacy Exchange tokens.
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
Important
Legacy Exchange user identity tokens and callback tokens will be turned off for all Exchange Online tenants in October 2024 as part of Microsoft’s Secure Future Initiative, which gives organizations the tools needed to respond to the current threat landscape. Exchange user identity tokens will still work for Exchange on-premises. Nested app authentication is the recommended approach for tokens going forward. For more information, see our blog post about nested app authentication and legacy Exchange tokens.
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
Office Add-ins
Feedback
https://aka.ms/ContentUserFeedback.
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see:Submit and view feedback for