Office.Mailbox interface

Provides access to the Microsoft Outlook add-in object model.

Key properties:

diagnostics: Provides diagnostic information to an Outlook add-in.
item: Provides methods and properties for accessing a message or appointment in an Outlook add-in.
userProfile: Provides information about the user in an Outlook add-in.

Remarks

Minimum permission level: restricted

Applicable Outlook mode: Compose or Read

Properties

diagnostics	Provides diagnostic information to an Outlook add-in. For information about the diagnostic properties you can access, see Office.Diagnostics.
ewsUrl	Gets the URL of the Exchange Web Services (EWS) endpoint for this email account.
item	The mailbox item. Depending on the context in which the add-in opened, the item type may vary. If you want to see IntelliSense for only a specific type or mode, cast this item to one of the following: MessageCompose, MessageRead, AppointmentCompose, AppointmentRead Important: When calling `Office.context.mailbox.item` on a message, note that the Reading Pane in the Outlook client must be turned on. For guidance on how to configure the Reading Pane, see Use and configure the Reading Pane to preview messages. `item` can be null if your add-in supports pinning the task pane. For details on how to handle, see Implement a pinnable task pane in Outlook.
masterCategories	Gets an object that provides methods to manage the categories master list associated with a mailbox.
restUrl	Gets the URL of the REST endpoint for this email account.
userProfile	Information about the user associated with the mailbox. This includes their account type, display name, email address, and time zone. More information is under Office.UserProfile

Methods

addHandlerAsync(eventType, handler, options, callback)	Adds an event handler for a supported event. Events are only available in task pane add-ins.
addHandlerAsync(eventType, handler, callback)	Adds an event handler for a supported event. Events are only available in task pane add-ins.
convertToEwsId(id, restVersion)	Converts a supported ID into the Exchange Web Services (EWS) format.
convertToLocalClientTime(timeValue)	Gets a dictionary containing time information in local client time. The time zone used by the Outlook client varies by platform. Outlook on Windows (classic) and on Mac use the client computer time zone. Outlook on the web and new Outlook on Windows use the time zone set on the Exchange Admin Center (EAC). You should handle date and time values so that the values you display on the user interface are always consistent with the time zone that the user expects. In Outlook on Windows (classic) and on Mac, the `convertToLocalClientTime` method returns a dictionary object with the values set to the client computer time zone. In Outlook on the web and new Outlook on Windows, the `convertToLocalClientTime` method returns a dictionary object with the values set to the time zone specified in the EAC.
convertToRestId(id, restVersion)	Converts a supported ID into REST format.
convertToUtcClientTime(input)	Gets a `Date` object from a dictionary containing time information. The `convertToUtcClientTime` method converts a dictionary containing a local date and time to a `Date` object with the correct values for the local date and time.
displayAppointmentForm(itemId)	Displays an existing calendar appointment. The `displayAppointmentForm` method opens an existing calendar appointment in a new window on the desktop. In Outlook on Mac, you can use this method to display a single appointment that isn't part of a recurring series, or the master appointment of a recurring series. However, you can't display an instance of the series because you can't access the properties (including the item ID) of instances of a recurring series. In Outlook on the web and new Outlook on Windows, this method opens the specified form only if the body of the form is less than or equal to 32K characters. If the specified item identifier does not identify an existing appointment, a blank pane opens on the client computer or device, and no error message is returned.
displayAppointmentFormAsync(itemId, options, callback)	Displays an existing calendar appointment. The `displayAppointmentFormAsync` method opens an existing calendar appointment in a new window on the desktop or in a dialog box on mobile devices. In Outlook on Mac, you can use this method to display a single appointment that is not part of a recurring series, or the master appointment of a recurring series. However, you can't display an instance of the series because you can't access the properties (including the item ID) of instances of a recurring series. In Outlook on the web and new Outlook on Windows, this method opens the specified form only if the body of the form is less than or equal to 32K characters. If the specified item identifier does not identify an existing appointment, a blank pane opens on the client computer or device, and no error message is returned. Note: This method isn't supported in Outlook on iOS or on Android.
displayAppointmentFormAsync(itemId, callback)	Displays an existing calendar appointment. The `displayAppointmentFormAsync` method opens an existing calendar appointment in a new window on the desktop or in a dialog box on mobile devices. In Outlook on Mac, you can use this method to display a single appointment that is not part of a recurring series, or the master appointment of a recurring series. However, you can't display an instance of the series because you can't access the properties (including the item ID) of instances of a recurring series. In Outlook on the web and new Outlook on Windows, this method opens the specified form only if the body of the form is less than or equal to 32K characters. If the specified item identifier does not identify an existing appointment, a blank pane opens on the client computer or device, and no error message is returned. Note: This method isn't supported in Outlook on iOS or on Android.
displayMessageForm(itemId)	Displays an existing message. The `displayMessageForm` method opens an existing message in a new window on the desktop. In Outlook on the web and new Outlook on Windows, this method opens the specified form only if the body of the form is less than or equal to 32K characters. If the specified item identifier doesn't identify an existing message, no message will be displayed on the client computer, and no error message is returned.
displayMessageFormAsync(itemId, options, callback)	Displays an existing message. The `displayMessageFormAsync` method opens an existing message in a new window on the desktop or in a dialog box on mobile devices. In Outlook on the web and new Outlook on Windows, this method opens the specified form only if the body of the form is less than or equal to 32K characters. If the specified item identifier does not identify an existing message, no message will be displayed on the client computer, and no error message is returned. Don't use the `displayMessageForm` or `displayMessageFormAsync` method with an itemId that represents an appointment. Use the `displayAppointmentForm` or `displayAppointmentFormAsync` method to display an existing appointment, and `displayNewAppointmentForm` or `displayNewAppointmentFormAsync` to display a form to create a new appointment. Note: This method isn't supported in Outlook on iOS or on Android.
displayMessageFormAsync(itemId, callback)	Displays an existing message. The `displayMessageFormAsync` method opens an existing message in a new window on the desktop or in a dialog box on mobile devices. In Outlook on the web and new Outlook on Windows, this method opens the specified form only if the body of the form is less than or equal to 32K characters. If the specified item identifier does not identify an existing message, no message will be displayed on the client computer, and no error message is returned. Don't use the `displayMessageForm` or `displayMessageFormAsync` method with an itemId that represents an appointment. Use the `displayAppointmentForm` or `displayAppointmentFormAsync` method to display an existing appointment, and `displayNewAppointmentForm` or `displayNewAppointmentFormAsync` to display a form to create a new appointment. Note: This method isn't supported in Outlook on iOS or on Android.
displayNewAppointmentForm(parameters)	Displays a form for creating a new calendar appointment. The `displayNewAppointmentForm` method opens a form that enables the user to create a new appointment or meeting. If parameters are specified, the appointment form fields are automatically populated with the contents of the parameters. In Outlook on the web and new Outlook on Windows, this method always displays a form with an attendees field. If you don't specify any attendees as input arguments, the method displays a form with a Save button. If you have specified attendees, the form would include the attendees and a Send button. In Outlook on Windows (classic) and on Mac, if you specify any attendees or resources in the `requiredAttendees`, `optionalAttendees`, or `resources` parameter, this method displays a meeting form with a Send button. If you don't specify any recipients, this method displays an appointment form with a Save & Close button. If any of the parameters exceed the specified size limits, or if an unknown parameter name is specified, an exception is thrown.
displayNewAppointmentFormAsync(parameters, options, callback)	Displays a form for creating a new calendar appointment. The `displayNewAppointmentFormAsync` method opens a form that enables the user to create a new appointment or meeting. If parameters are specified, the appointment form fields are automatically populated with the contents of the parameters. In Outlook on the web and new Outlook on Windows, this method always displays a form with an attendees field. If you do not specify any attendees as input arguments, the method displays a form with a Save button. If you have specified attendees, the form would include the attendees and a Send button. In Outlook on Windows (classic) and on Mac, if you specify any attendees or resources in the `requiredAttendees`, `optionalAttendees`, or `resources` parameter, this method displays a meeting form with a Send button. If you don't specify any recipients, this method displays an appointment form with a Save & Close button. If any of the parameters exceed the specified size limits, or if an unknown parameter name is specified, an exception is thrown. Note: This method isn't supported in Outlook on iOS or on Android.
displayNewAppointmentFormAsync(parameters, callback)	Displays a form for creating a new calendar appointment. The `displayNewAppointmentFormAsync` method opens a form that enables the user to create a new appointment or meeting. If parameters are specified, the appointment form fields are automatically populated with the contents of the parameters. In Outlook on the web and new Outlook on Windows, this method always displays a form with an attendees field. If you do not specify any attendees as input arguments, the method displays a form with a Save button. If you have specified attendees, the form would include the attendees and a Send button. In Outlook on Windows (classic) and on Mac, if you specify any attendees or resources in the `requiredAttendees`, `optionalAttendees`, or `resources` parameter, this method displays a meeting form with a Send button. If you don't specify any recipients, this method displays an appointment form with a Save & Close button. If any of the parameters exceed the specified size limits, or if an unknown parameter name is specified, an exception is thrown. Note: This method isn't supported in Outlook on iOS or on Android.
displayNewMessageForm(parameters)	Displays a form for creating a new message. The `displayNewMessageForm` method opens a form that enables the user to create a new message. If parameters are specified, the message form fields are automatically populated with the contents of the parameters. If any of the parameters exceed the specified size limits, or if an unknown parameter name is specified, an exception is thrown.
displayNewMessageFormAsync(parameters, options, callback)	Displays a form for creating a new message. The `displayNewMessageFormAsync` method opens a form that enables the user to create a new message. If parameters are specified, the message form fields are automatically populated with the contents of the parameters. If any of the parameters exceed the specified size limits, or if an unknown parameter name is specified, an exception is thrown.
displayNewMessageFormAsync(parameters, callback)	Displays a form for creating a new message. The `displayNewMessageFormAsync` method opens a form that enables the user to create a new message. If parameters are specified, the message form fields are automatically populated with the contents of the parameters. If any of the parameters exceed the specified size limits, or if an unknown parameter name is specified, an exception is thrown.
getCallbackTokenAsync(options, callback)	Gets a string that contains a token used to call REST APIs or Exchange Web Services (EWS). The `getCallbackTokenAsync` method makes an asynchronous call to get an opaque token from the Exchange Server that hosts the user's mailbox. The lifetime of the callback token is 5 minutes. The token is returned as a string in the `asyncResult.value` property.
getCallbackTokenAsync(callback, userContext)	Gets a string that contains a token used to get an attachment or item from an Exchange Server. The `getCallbackTokenAsync` method makes an asynchronous call to get an opaque token from the Exchange Server that hosts the user's mailbox. The lifetime of the callback token is 5 minutes. The token is returned as a string in the `asyncResult.value` property.
getIsIdentityManaged()	Returns true if the current mailbox is managed by Microsoft Intune.
getIsOpenFromLocationAllowed(openLocation)	Returns true if an organization's Intune mobile application management (MAM) policy allows an add-in to access data from the specified location.
getIsSaveToLocationAllowed(saveLocation)	Returns true if an organization's Intune mobile application management (MAM) policy allows an add-in to save data to the specified location.
getSelectedItemsAsync(options, callback)	Gets currently selected messages on which an add-in can activate and perform operations. An add-in can activate on a maximum of 100 messages at a time. To learn more about item multi-select, see Activate your Outlook add-in on multiple messages.
getSelectedItemsAsync(callback)	Gets currently selected messages on which an add-in can activate and perform operations. An add-in can activate on a maximum of 100 messages at a time. To learn more about item multi-select, see Activate your Outlook add-in on multiple messages.
getUserIdentityTokenAsync(callback, userContext)	Gets a token identifying the user and the Office Add-in. The token is returned as a string in the `asyncResult.value` property.
loadItemByIdAsync(itemId, options, callback)	Loads a single mail item by its Exchange Web Services (EWS) ID. Then, gets an object that provides the properties and methods of the loaded item.
loadItemByIdAsync(itemId, callback)	Loads a single mail item by its Exchange Web Services (EWS) ID. Then, gets an object that provides the properties and methods of the loaded item.
makeEwsRequestAsync(data, callback, userContext)	Makes an asynchronous request to an Exchange Web Services (EWS) service on the Exchange server that hosts the user's mailbox. The `makeEwsRequestAsync` method sends an EWS request on behalf of the add-in to Exchange.
removeHandlerAsync(eventType, options, callback)	Removes the event handlers for a supported event type. Events are only available in task pane add-ins.
removeHandlerAsync(eventType, callback)	Removes the event handlers for a supported event type. Events are only available in task pane add-ins.

diagnostics

Provides diagnostic information to an Outlook add-in.

For information about the diagnostic properties you can access, see Office.Diagnostics.

diagnostics: Diagnostics;

Property Value

Office.Diagnostics

Remarks

Minimum permission level: read item

Applicable Outlook mode: Compose or Read

Starting with Mailbox requirement set 1.5, you can also use the Office.context.diagnostics property to get similar information.

ewsUrl

Gets the URL of the Exchange Web Services (EWS) endpoint for this email account.

ewsUrl: string;

Property Value

string

Remarks

[Api set: Mailbox 1.1]

Minimum permission level: read item

Applicable Outlook mode: Compose or Read

Important:

Your app must have the read item permission specified in its manifest to call the ewsUrl member in read mode.
In compose mode, you must call the saveAsync method before you can use the ewsUrl member. Your app must have read/write item permissions to call the saveAsync method.
This property isn't supported in Outlook on Android or on iOS. For more information on supported APIs in Outlook mobile, see Outlook JavaScript APIs supported in Outlook on mobile devices.
The ewsUrl value can be used by a remote service to make EWS calls to the user's mailbox. For example, you can create a remote service to get attachments from the selected item.

item

The mailbox item. Depending on the context in which the add-in opened, the item type may vary. If you want to see IntelliSense for only a specific type or mode, cast this item to one of the following:

MessageCompose, MessageRead, AppointmentCompose, AppointmentRead

Important:

When calling Office.context.mailbox.item on a message, note that the Reading Pane in the Outlook client must be turned on. For guidance on how to configure the Reading Pane, see Use and configure the Reading Pane to preview messages.
item can be null if your add-in supports pinning the task pane. For details on how to handle, see Implement a pinnable task pane in Outlook.

item?: Item & ItemCompose & ItemRead & Message & MessageCompose & MessageRead & Appointment & AppointmentCompose & AppointmentRead;

Property Value

Office.Item & Office.ItemCompose & Office.ItemRead & Office.Message & Office.MessageCompose & Office.MessageRead & Office.Appointment & Office.AppointmentCompose & Office.AppointmentRead

masterCategories

Gets an object that provides methods to manage the categories master list associated with a mailbox.

masterCategories: MasterCategories;

Property Value

Office.MasterCategories

Remarks

[Api set: Mailbox 1.8]

Minimum permission level: read/write mailbox

Applicable Outlook mode: Compose or Read

restUrl

Gets the URL of the REST endpoint for this email account.

restUrl: string;

Property Value

string

Remarks

[Api set: Mailbox 1.5]

Minimum permission level: read item

Applicable Outlook mode: Compose or Read

Important:

The Outlook REST v2.0 and beta endpoints are now deprecated. However, privately released and AppSource-hosted add-ins are able to use the REST service until extended support ends for Outlook 2019 on October 14, 2025. Traffic from these add-ins is automatically identified for exemption. This exemption also applies to new add-ins developed after March 31, 2024. Although add-ins are able to use the REST service until 2025, we highly encourage you to migrate your add-ins to use Microsoft Graph. For guidance, see Compare Microsoft Graph and Outlook REST API endpoints.
Your add-in must have the read item permission specified in its manifest to call the restUrl member in read mode.
In compose mode you must call the saveAsync method before you can use the restUrl member. Your add-in must have read/write item permissions to call the saveAsync method. However, in delegate or shared scenarios, you should instead use the targetRestUrl property of the SharedProperties object (introduced in requirement set 1.8). For more information, see the shared folders and shared mailbox article.

userProfile

Information about the user associated with the mailbox. This includes their account type, display name, email address, and time zone.

More information is under Office.UserProfile

userProfile: UserProfile;

Property Value

Office.UserProfile

addHandlerAsync(eventType, handler, options, callback)

Adds an event handler for a supported event. Events are only available in task pane add-ins.

addHandlerAsync(eventType: Office.EventType | string, handler: any, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameters

eventType: Office.EventType | string

The event that should invoke the handler.

handler: any

The function to handle the event. The function must accept a single parameter, which is an object literal. The type property on the parameter will match the eventType parameter passed to addHandlerAsync.

options: Office.AsyncContextOptions

Provides an option for preserving context data of any type, unchanged, for use in a callback.

callback: (asyncResult: Office.AsyncResult<void>) => void

Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type Office.AsyncResult.

Returns

void

Remarks

[Api set: Mailbox 1.5]

Minimum permission level: read item

Applicable Outlook mode: Compose or Read

Important: The following events are supported on the Mailbox object.

Event	Description	Minimum requirement set
`DragAndDropEvent`	A message or file attachment in the Outlook client window is dragged then dropped into the task pane of an add-in. This event is only supported in Outlook on the web and the new Outlook on Windows.	1.5
`ItemChanged`	A different Outlook item is selected for viewing while the task pane is pinned.	1.5
`OfficeThemeChanged`	The OfficeTheme is changed in Outlook.	1.14
`SelectedItemsChanged`	One or more messages are selected or deselected.	1.13

addHandlerAsync(eventType, handler, callback)

Adds an event handler for a supported event. Events are only available in task pane add-ins.

addHandlerAsync(eventType: Office.EventType | string, handler: any, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameters

eventType: Office.EventType | string

The event that should invoke the handler.

handler: any

The function to handle the event. The function must accept a single parameter, which is an object literal. The type property on the parameter will match the eventType parameter passed to addHandlerAsync.

callback: (asyncResult: Office.AsyncResult<void>) => void

Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type Office.AsyncResult.

Returns

void

Remarks

[Api set: Mailbox 1.5]

Minimum permission level: read item

Applicable Outlook mode: Compose or Read

Important: The following events are supported on the Mailbox object.

Event	Description	Minimum requirement set
`DragAndDropEvent`	A message or file attachment in the Outlook client window is dragged then dropped into the task pane of an add-in. This event is only supported in Outlook on the web and the new Outlook on Windows.	1.5
`ItemChanged`	A different Outlook item is selected for viewing while the task pane is pinned.	1.5
`OfficeThemeChanged`	The OfficeTheme is changed in Outlook.	1.14
`SelectedItemsChanged`	One or more messages are selected or deselected.	1.13

convertToEwsId(id, restVersion)

Converts a supported ID into the Exchange Web Services (EWS) format.

convertToEwsId(id: string, restVersion: MailboxEnums.RestVersion | string): string;

Parameters

id: string

The ID to be converted into EWS format. This string can be an item ID formatted for the Outlook REST APIs or a conversation ID retrieved from Office.context.mailbox.item.conversationId.

restVersion: Office.MailboxEnums.RestVersion | string

A value indicating the version of the Outlook REST API used to retrieve the item ID.

Returns

string

Remarks

[Api set: Mailbox 1.3]

Minimum permission level: restricted

Applicable Outlook mode: Compose or Read

Important:

Legacy Exchange Online user identity tokens and callback tokens are no longer supported and are turned off across all Microsoft 365 tenants. If an Outlook add-in requires delegated user access or user identity, we recommend using MSAL (Microsoft Authentication Library) and nested app authentication. Exchange user identity tokens are still supported for Exchange on-premises.
This method isn't supported in Outlook on Android or on iOS. For more information on supported APIs in Outlook mobile, see Outlook JavaScript APIs supported in Outlook on mobile devices.
Item IDs retrieved via a REST API (such as Microsoft Graph) use a different format than the format used by EWS. The convertToEwsId method converts a REST-formatted ID into the proper format for EWS.

convertToLocalClientTime(timeValue)

Gets a dictionary containing time information in local client time.

The time zone used by the Outlook client varies by platform. Outlook on Windows (classic) and on Mac use the client computer time zone. Outlook on the web and new Outlook on Windows use the time zone set on the Exchange Admin Center (EAC). You should handle date and time values so that the values you display on the user interface are always consistent with the time zone that the user expects.

In Outlook on Windows (classic) and on Mac, the convertToLocalClientTime method returns a dictionary object with the values set to the client computer time zone. In Outlook on the web and new Outlook on Windows, the convertToLocalClientTime method returns a dictionary object with the values set to the time zone specified in the EAC.

convertToLocalClientTime(timeValue: Date): LocalClientTime;

Parameters

timeValue: Date

A Date object.

Returns

Office.LocalClientTime

Remarks

Minimum permission level: read item

Applicable Outlook mode: Compose or Read

convertToRestId(id, restVersion)

Converts a supported ID into REST format.

convertToRestId(id: string, restVersion: MailboxEnums.RestVersion | string): string;

Parameters

id: string

The ID to be converted into REST format. This string can be an item ID formatted for EWS that's usually retrieved from Office.context.mailbox.item.itemId, a conversation ID retrieved from Office.context.mailbox.item.conversationId, or a series ID retrieved from Office.context.mailbox.item.seriesId.

restVersion: Office.MailboxEnums.RestVersion | string

A value indicating the version of the Outlook REST API used with the converted ID.

Returns

string

Remarks

[Api set: Mailbox 1.3]

Minimum permission level: restricted

Applicable Outlook mode: Compose or Read

Important:

This method isn't supported in Outlook on Android or on iOS. For more information on supported APIs in Outlook mobile, see Outlook JavaScript APIs supported in Outlook on mobile devices.
Item IDs retrieved via Exchange Web Services (EWS) or via the itemId property use a different format than the format used by REST APIs (such as Microsoft Graph). The convertToRestId method converts an EWS-formatted ID into the proper format for REST.

convertToUtcClientTime(input)

Gets a Date object from a dictionary containing time information.

The convertToUtcClientTime method converts a dictionary containing a local date and time to a Date object with the correct values for the local date and time.

convertToUtcClientTime(input: LocalClientTime): Date;

Parameters

input: Office.LocalClientTime

The local time value to convert.

Returns

Date

A Date object with the time expressed in UTC.

Remarks

Minimum permission level: read item

Applicable Outlook mode: Compose or Read

displayAppointmentForm(itemId)

Displays an existing calendar appointment.

The displayAppointmentForm method opens an existing calendar appointment in a new window on the desktop.

In Outlook on Mac, you can use this method to display a single appointment that isn't part of a recurring series, or the master appointment of a recurring series. However, you can't display an instance of the series because you can't access the properties (including the item ID) of instances of a recurring series.

In Outlook on the web and new Outlook on Windows, this method opens the specified form only if the body of the form is less than or equal to 32K characters.

If the specified item identifier does not identify an existing appointment, a blank pane opens on the client computer or device, and no error message is returned.

displayAppointmentForm(itemId: string): void;

Parameters

itemId: string

The Exchange Web Services (EWS) identifier for an existing calendar appointment.

Returns

void

Remarks

[Api set: Mailbox 1.1]

Minimum permission level: read item

Applicable Outlook mode: Compose or Read

Important: This method isn't supported in Outlook on Android or on iOS. For more information on supported APIs in Outlook mobile, see Outlook JavaScript APIs supported in Outlook on mobile devices.

displayAppointmentFormAsync(itemId, options, callback)

Displays an existing calendar appointment.

The displayAppointmentFormAsync method opens an existing calendar appointment in a new window on the desktop or in a dialog box on mobile devices.

In Outlook on Mac, you can use this method to display a single appointment that is not part of a recurring series, or the master appointment of a recurring series. However, you can't display an instance of the series because you can't access the properties (including the item ID) of instances of a recurring series.

In Outlook on the web and new Outlook on Windows, this method opens the specified form only if the body of the form is less than or equal to 32K characters.

If the specified item identifier does not identify an existing appointment, a blank pane opens on the client computer or device, and no error message is returned.

Note: This method isn't supported in Outlook on iOS or on Android.

displayAppointmentFormAsync(itemId: string, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameters

itemId: string

The Exchange Web Services (EWS) identifier for an existing calendar appointment.

options: Office.AsyncContextOptions

An object literal that contains one or more of the following properties:- asyncContext: Developers can provide any object they wish to access in the callback function.

callback: (asyncResult: Office.AsyncResult<void>) => void

Optional. When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an Office.AsyncResult object.

Returns

void

Remarks

[Api set: Mailbox 1.9]

Minimum permission level: read item

Applicable Outlook mode: Compose or Read

displayAppointmentFormAsync(itemId, callback)

Displays an existing calendar appointment.

The displayAppointmentFormAsync method opens an existing calendar appointment in a new window on the desktop or in a dialog box on mobile devices.

In Outlook on Mac, you can use this method to display a single appointment that is not part of a recurring series, or the master appointment of a recurring series. However, you can't display an instance of the series because you can't access the properties (including the item ID) of instances of a recurring series.

In Outlook on the web and new Outlook on Windows, this method opens the specified form only if the body of the form is less than or equal to 32K characters.

If the specified item identifier does not identify an existing appointment, a blank pane opens on the client computer or device, and no error message is returned.

Note: This method isn't supported in Outlook on iOS or on Android.

displayAppointmentFormAsync(itemId: string, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameters

itemId: string

The Exchange Web Services (EWS) identifier for an existing calendar appointment.

callback: (asyncResult: Office.AsyncResult<void>) => void

Optional. When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an Office.AsyncResult object.

Returns

void

Remarks

[Api set: Mailbox 1.9]

Minimum permission level: read item

Applicable Outlook mode: Compose or Read

displayMessageForm(itemId)

Displays an existing message.

The displayMessageForm method opens an existing message in a new window on the desktop.

In Outlook on the web and new Outlook on Windows, this method opens the specified form only if the body of the form is less than or equal to 32K characters.

If the specified item identifier doesn't identify an existing message, no message will be displayed on the client computer, and no error message is returned.

displayMessageForm(itemId: string): void;

Parameters

itemId: string

The Exchange Web Services (EWS) identifier for an existing message.

Returns

void

Remarks

[Api set: Mailbox 1.1]

Minimum permission level: read item

Applicable Outlook mode: Compose or Read

Important:

This method isn't supported in Outlook on Android or on iOS. For more information on supported APIs in Outlook mobile, see Outlook JavaScript APIs supported in Outlook on mobile devices.
Don't use the displayMessageForm with an itemId that represents an appointment. Use the displayAppointmentForm method to display an existing appointment, and displayNewAppointmentForm to display a form to create a new appointment.

displayMessageFormAsync(itemId, options, callback)

Displays an existing message.

The displayMessageFormAsync method opens an existing message in a new window on the desktop or in a dialog box on mobile devices.

In Outlook on the web and new Outlook on Windows, this method opens the specified form only if the body of the form is less than or equal to 32K characters.

If the specified item identifier does not identify an existing message, no message will be displayed on the client computer, and no error message is returned.

Don't use the displayMessageForm or displayMessageFormAsync method with an itemId that represents an appointment. Use the displayAppointmentForm or displayAppointmentFormAsync method to display an existing appointment, and displayNewAppointmentForm or displayNewAppointmentFormAsync to display a form to create a new appointment.

Note: This method isn't supported in Outlook on iOS or on Android.

displayMessageFormAsync(itemId: string, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameters

itemId: string

The Exchange Web Services (EWS) identifier for an existing message.

options: Office.AsyncContextOptions

An object literal that contains one or more of the following properties:- asyncContext: Developers can provide any object they wish to access in the callback function.

callback: (asyncResult: Office.AsyncResult<void>) => void

Optional. When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an Office.AsyncResult object.

Returns

void

Remarks

[Api set: Mailbox 1.9]

Minimum permission level: read item

Applicable Outlook mode: Compose or Read

displayMessageFormAsync(itemId, callback)

Displays an existing message.

The displayMessageFormAsync method opens an existing message in a new window on the desktop or in a dialog box on mobile devices.

In Outlook on the web and new Outlook on Windows, this method opens the specified form only if the body of the form is less than or equal to 32K characters.

If the specified item identifier does not identify an existing message, no message will be displayed on the client computer, and no error message is returned.

Don't use the displayMessageForm or displayMessageFormAsync method with an itemId that represents an appointment. Use the displayAppointmentForm or displayAppointmentFormAsync method to display an existing appointment, and displayNewAppointmentForm or displayNewAppointmentFormAsync to display a form to create a new appointment.

Note: This method isn't supported in Outlook on iOS or on Android.

displayMessageFormAsync(itemId: string, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameters

itemId: string

The Exchange Web Services (EWS) identifier for an existing message.

callback: (asyncResult: Office.AsyncResult<void>) => void

Optional. When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an Office.AsyncResult object.

Returns

void

Remarks

[Api set: Mailbox 1.9]

Minimum permission level: read item

Applicable Outlook mode: Compose or Read

displayNewAppointmentForm(parameters)

Displays a form for creating a new calendar appointment.

The displayNewAppointmentForm method opens a form that enables the user to create a new appointment or meeting. If parameters are specified, the appointment form fields are automatically populated with the contents of the parameters.

In Outlook on the web and new Outlook on Windows, this method always displays a form with an attendees field. If you don't specify any attendees as input arguments, the method displays a form with a Save button. If you have specified attendees, the form would include the attendees and a Send button.

In Outlook on Windows (classic) and on Mac, if you specify any attendees or resources in the requiredAttendees, optionalAttendees, or resources parameter, this method displays a meeting form with a Send button. If you don't specify any recipients, this method displays an appointment form with a Save & Close button.

If any of the parameters exceed the specified size limits, or if an unknown parameter name is specified, an exception is thrown.

displayNewAppointmentForm(parameters: AppointmentForm): void;

Parameters

parameters: Office.AppointmentForm

An AppointmentForm describing the new appointment. All properties are optional.

Returns

void

Remarks

[Api set: Mailbox 1.1]

Minimum permission level: read item

Applicable Outlook mode: Read

Important: This method isn't supported in Outlook on Android or on iOS. For more information on supported APIs in Outlook mobile, see Outlook JavaScript APIs supported in Outlook on mobile devices.

displayNewAppointmentFormAsync(parameters, options, callback)

Displays a form for creating a new calendar appointment.

The displayNewAppointmentFormAsync method opens a form that enables the user to create a new appointment or meeting. If parameters are specified, the appointment form fields are automatically populated with the contents of the parameters.

In Outlook on the web and new Outlook on Windows, this method always displays a form with an attendees field. If you do not specify any attendees as input arguments, the method displays a form with a Save button. If you have specified attendees, the form would include the attendees and a Send button.

In Outlook on Windows (classic) and on Mac, if you specify any attendees or resources in the requiredAttendees, optionalAttendees, or resources parameter, this method displays a meeting form with a Send button. If you don't specify any recipients, this method displays an appointment form with a Save & Close button.

If any of the parameters exceed the specified size limits, or if an unknown parameter name is specified, an exception is thrown.

Note: This method isn't supported in Outlook on iOS or on Android.

displayNewAppointmentFormAsync(parameters: AppointmentForm, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameters

parameters: Office.AppointmentForm

An AppointmentForm describing the new appointment. All properties are optional.

options: Office.AsyncContextOptions

An object literal that contains one or more of the following properties:- asyncContext: Developers can provide any object they wish to access in the callback function.

callback: (asyncResult: Office.AsyncResult<void>) => void

Optional. When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an Office.AsyncResult object.

Returns

void

Remarks

[Api set: Mailbox 1.9]

Minimum permission level: read item

Applicable Outlook mode: Read

displayNewAppointmentFormAsync(parameters, callback)

Displays a form for creating a new calendar appointment.

The displayNewAppointmentFormAsync method opens a form that enables the user to create a new appointment or meeting. If parameters are specified, the appointment form fields are automatically populated with the contents of the parameters.

In Outlook on the web and new Outlook on Windows, this method always displays a form with an attendees field. If you do not specify any attendees as input arguments, the method displays a form with a Save button. If you have specified attendees, the form would include the attendees and a Send button.

In Outlook on Windows (classic) and on Mac, if you specify any attendees or resources in the requiredAttendees, optionalAttendees, or resources parameter, this method displays a meeting form with a Send button. If you don't specify any recipients, this method displays an appointment form with a Save & Close button.

If any of the parameters exceed the specified size limits, or if an unknown parameter name is specified, an exception is thrown.

Note: This method isn't supported in Outlook on iOS or on Android.

displayNewAppointmentFormAsync(parameters: AppointmentForm, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameters

parameters: Office.AppointmentForm

An AppointmentForm describing the new appointment. All properties are optional.

callback: (asyncResult: Office.AsyncResult<void>) => void

Optional. When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an Office.AsyncResult object.

Returns

void

Remarks

[Api set: Mailbox 1.9]

Minimum permission level: read item

Applicable Outlook mode: Read

displayNewMessageForm(parameters)

Displays a form for creating a new message.

The displayNewMessageForm method opens a form that enables the user to create a new message. If parameters are specified, the message form fields are automatically populated with the contents of the parameters.

If any of the parameters exceed the specified size limits, or if an unknown parameter name is specified, an exception is thrown.

displayNewMessageForm(parameters: MessageForm): void;

Parameters

parameters: Office.MessageForm

A MessageForm object containing the content to be added to the new message form. All properties are optional.

Returns

void

Remarks

[Api set: Mailbox 1.6]

Minimum permission level: read item

Applicable Outlook mode: Read

displayNewMessageFormAsync(parameters, options, callback)

Displays a form for creating a new message.

The displayNewMessageFormAsync method opens a form that enables the user to create a new message. If parameters are specified, the message form fields are automatically populated with the contents of the parameters.

If any of the parameters exceed the specified size limits, or if an unknown parameter name is specified, an exception is thrown.

displayNewMessageFormAsync(parameters: MessageForm, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameters

parameters: Office.MessageForm

A MessageForm object containing the content to be added to the new message form. All properties are optional.

options: Office.AsyncContextOptions

An object literal that contains one or more of the following properties:- asyncContext: Developers can provide any object they wish to access in the callback function.

callback: (asyncResult: Office.AsyncResult<void>) => void

Optional. When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an Office.AsyncResult object.

Returns

void

Remarks

[Api set: Mailbox 1.9]

Minimum permission level: read item

Applicable Outlook mode: Read

displayNewMessageFormAsync(parameters, callback)

Displays a form for creating a new message.

The displayNewMessageFormAsync method opens a form that enables the user to create a new message. If parameters are specified, the message form fields are automatically populated with the contents of the parameters.

If any of the parameters exceed the specified size limits, or if an unknown parameter name is specified, an exception is thrown.

displayNewMessageFormAsync(parameters: MessageForm, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameters

parameters: Office.MessageForm

A MessageForm object containing the content to be added to the new message form. All properties are optional.

callback: (asyncResult: Office.AsyncResult<void>) => void

Optional. When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an Office.AsyncResult object.

Returns

void

Remarks

[Api set: Mailbox 1.9]

Minimum permission level: read item

Applicable Outlook mode: Read

getCallbackTokenAsync(options, callback)

Gets a string that contains a token used to call REST APIs or Exchange Web Services (EWS).

The getCallbackTokenAsync method makes an asynchronous call to get an opaque token from the Exchange Server that hosts the user's mailbox. The lifetime of the callback token is 5 minutes.

The token is returned as a string in the asyncResult.value property.

getCallbackTokenAsync(options: Office.AsyncContextOptions & { isRest?: boolean }, callback: (asyncResult: Office.AsyncResult<string>) => void): void;

Parameters

options: Office.AsyncContextOptions & { isRest?: boolean }

An object literal that contains one or more of the following properties:- isRest: Determines if the token provided will be used for the Outlook REST APIs or Exchange Web Services. Default value is false. asyncContext: Any state data that is passed to the asynchronous method.

callback: (asyncResult: Office.AsyncResult<string>) => void

When the method completes, the function passed in the callback parameter is called with a single parameter of type Office.AsyncResult. The token is returned as a string in the asyncResult.value property. If there was an error, the asyncResult.error and asyncResult.diagnostics properties may provide additional information.

Returns

void

Remarks

[Api set: Mailbox 1.5]

Minimum permission level: read item

Applicable Outlook mode: Compose or Read

Important:

Legacy Exchange Online user identity tokens and callback tokens are no longer supported and are turned off across all Microsoft 365 tenants. If an Outlook add-in requires delegated user access or user identity, we recommend using MSAL (Microsoft Authentication Library) and nested app authentication (NAA). Exchange user identity tokens are still supported for Exchange on-premises.
The Outlook REST v2.0 and beta endpoints are now deprecated. However, privately released and AppSource-hosted add-ins are able to use the REST service until extended support ends for Outlook 2019 on October 14, 2025. Traffic from these add-ins is automatically identified for exemption. This exemption also applies to new add-ins developed after March 31, 2024. Although add-ins are able to use the REST service until 2025, we highly encourage you to migrate your add-ins to use Microsoft Graph. For guidance, see Compare Microsoft Graph and Outlook REST API endpoints.
This method isn't supported if you load an add-in in an Outlook.com or Gmail mailbox.
This method is only supported in read mode in Outlook on Android and on iOS. For more information on supported APIs in Outlook mobile, see Outlook JavaScript APIs supported in Outlook on mobile devices.
EWS operations aren't supported in add-ins running in Outlook on iOS and on Android. A REST token is always returned in Outlook mobile clients even if options.isRest is set to false.
Calling the getCallbackTokenAsync method in read mode requires a minimum permission level of read item.
Calling the getCallbackTokenAsync method in compose mode requires you to have saved the item. The saveAsync method requires a minimum permission level of read/write item.
For guidance on delegate or shared scenarios, see the shared folders and shared mailbox article.

REST Tokens

When a REST token is requested (options.isRest = true), the resulting token won't work to authenticate EWS calls. The token will be limited in scope to read-only access to the current item and its attachments, unless the add-in has specified the read/write mailbox permission in its manifest. If the read/write mailbox permission is specified, the resulting token will grant read/write access to mail, calendar, and contacts, including the ability to send mail.

The add-in should use the restUrl property to determine the correct URL to use when making REST API calls.

This API works for the following scopes.

Mail.ReadWrite
Mail.Send
Calendars.ReadWrite
Contacts.ReadWrite

EWS Tokens

When an EWS token is requested (options.isRest = false), the resulting token won't work to authenticate REST API calls. The token will be limited in scope to accessing the current item.

The add-in should use the ewsUrl property to determine the correct URL to use when making EWS calls.

You can pass both the token and either an attachment identifier or item identifier to an external system. That system uses the token as a bearer authorization token to call the Exchange Web Services (EWS) GetAttachment operation or GetItem operation to return an attachment or item. For example, you can create a remote service to get attachments from the selected item.

Errors:

If your call fails, use the asyncResult.diagnostics property to view details about the error.

GenericTokenError: An internal error has occurred. - In Exchange Online environments, this error occurs when the token can't be retrieved because legacy Exchange tokens for Outlook add-ins are turned off. We recommend using NAA as a single sign-on solution for your add-in.
HTTPRequestFailure: The request has failed. Please look at the diagnostics object for the HTTP error code.
InternalServerError: The Exchange server returned an error. Please look at the diagnostics object for more information. - In Exchange Online environments, this error occurs when the token can't be retrieved because legacy Exchange tokens for Outlook add-ins are turned off. We recommend using NAA as a single sign-on solution for your add-in.
NetworkError: The user is no longer connected to the network. Please check your network connection and try again.

getCallbackTokenAsync(callback, userContext)

Gets a string that contains a token used to get an attachment or item from an Exchange Server.

The getCallbackTokenAsync method makes an asynchronous call to get an opaque token from the Exchange Server that hosts the user's mailbox. The lifetime of the callback token is 5 minutes.

The token is returned as a string in the asyncResult.value property.

getCallbackTokenAsync(callback: (asyncResult: Office.AsyncResult<string>) => void, userContext?: any): void;

Parameters

callback: (asyncResult: Office.AsyncResult<string>) => void

When the method completes, the function passed in the callback parameter is called with a single parameter of type Office.AsyncResult. The token is returned as a string in the asyncResult.value property. If there was an error, the asyncResult.error and asyncResult.diagnostics properties may provide additional information.

userContext: any

Optional. Any state data that is passed to the asynchronous method.

Returns

void

Remarks

[Api set: All support Read mode; Mailbox 1.3 introduced Compose mode support]

Minimum permission level: read item

Applicable Outlook mode: Compose or Read

Important:

Legacy Exchange Online user identity tokens and callback tokens are no longer supported and are turned off across all Microsoft 365 tenants. If an Outlook add-in requires delegated user access or user identity, we recommend using MSAL (Microsoft Authentication Library) and nested app authentication (NAA). Exchange user identity tokens are still supported for Exchange on-premises.
You can pass both the token and either an attachment identifier or item identifier to an external system. That system uses the token as a bearer authorization token to call the Exchange Web Services (EWS) GetAttachment or GetItem operation to return an attachment or item. For example, you can create a remote service to get attachments from the selected item.
Calling the getCallbackTokenAsync method in read mode requires a minimum permission level of read item.
Calling the getCallbackTokenAsync method in compose mode requires you to have saved the item. The saveAsync method requires a minimum permission level of read/write item.
This method isn't supported in Outlook on Android or on iOS. EWS operations aren't supported in add-ins running in Outlook on mobile clients. For more information on supported APIs in Outlook mobile, see Outlook JavaScript APIs supported in Outlook on mobile devices.
This method isn't supported if you load an add-in in an Outlook.com or Gmail mailbox.
For guidance on delegate or shared scenarios, see the shared folders and shared mailbox article.

Errors:

If your call fails, use the asyncResult.diagnostics property to view details about the error.

GenericTokenError: An internal error has occurred. - In Exchange Online environments, this error occurs when the token can't be retrieved because legacy Exchange tokens for Outlook add-ins are turned off. We recommend using NAA as a single sign-on solution for your add-in.
HTTPRequestFailure: The request has failed. Please look at the diagnostics object for the HTTP error code.
InternalServerError: The Exchange server returned an error. Please look at the diagnostics object for more information. - In Exchange Online environments, this error occurs when the token can't be retrieved because legacy Exchange tokens for Outlook add-ins are turned off. We recommend using NAA as a single sign-on solution for your add-in.
NetworkError: The user is no longer connected to the network. Please check your network connection and try again.

getIsIdentityManaged()

Returns true if the current mailbox is managed by Microsoft Intune.

getIsIdentityManaged(): boolean;

Returns

boolean

True if the current mailbox is managed by Microsoft Intune.

Remarks

Minimum permission level: read item

Applicable Outlook mode: Compose, Read

Important: This method is only supported in Outlook on Android and on iOS starting in Version 4.2443.0.To learn more about APIs supported in Outlook on mobile devices, see Outlook JavaScript APIs supported in Outlook on mobile devices.

Errors:

MAMServiceNotAvailable: The client is unable to fetch the mobile application management (MAM) policy.

getIsOpenFromLocationAllowed(openLocation)

Returns true if an organization's Intune mobile application management (MAM) policy allows an add-in to access data from the specified location.

getIsOpenFromLocationAllowed(openLocation: MailboxEnums.OpenLocation): boolean;

Parameters

openLocation: Office.MailboxEnums.OpenLocation

The location from which the add-in is attempting to access data.

Returns

boolean

True if an organization's Intune MAM policy allows an add-in to access data from the specified location.

Remarks

Minimum permission level: read item

Applicable Outlook mode: Compose, Read

Important: This method is only supported in Outlook on Android and on iOS starting in Version 4.2443.0. To learn more about APIs supported in Outlook on mobile devices, see Outlook JavaScript APIs supported in Outlook on mobile devices.

Errors:

InvalidOpenLocationInput: The value of the specified location is invalid.
MAMServiceNotAvailable: The client is unable to fetch the MAM policy.

getIsSaveToLocationAllowed(saveLocation)

Returns true if an organization's Intune mobile application management (MAM) policy allows an add-in to save data to the specified location.

getIsSaveToLocationAllowed(saveLocation: MailboxEnums.SaveLocation): boolean;

Parameters

saveLocation: Office.MailboxEnums.SaveLocation

The location in which the add-in is attempting to save data.

Returns

boolean

True if an organization's Intune MAM policy allows an add-in to save data to the specified location.

Remarks

Minimum permission level: read item

Applicable Outlook mode: Compose, Read

Important: This method is only supported in Outlook on Android and on iOS starting in Version 4.2443.0. To learn more about APIs supported in Outlook on mobile devices, see Outlook JavaScript APIs supported in Outlook on mobile devices.

Errors:

InvalidSaveLocationInput: The value of the specified location is invalid.
MAMServiceNotAvailable: The client is unable to fetch the MAM policy.

getSelectedItemsAsync(options, callback)

Gets currently selected messages on which an add-in can activate and perform operations. An add-in can activate on a maximum of 100 messages at a time. To learn more about item multi-select, see Activate your Outlook add-in on multiple messages.

getSelectedItemsAsync(options: Office.AsyncContextOptions, callback: (asyncResult: Office.AsyncResult<SelectedItemDetails[]>) => void): void;

Parameters

options: Office.AsyncContextOptions

An object literal that contains one or more of the following properties:- asyncContext: Developers can provide any object they wish to access in the callback function.

callback: (asyncResult: Office.AsyncResult<Office.SelectedItemDetails[]>) => void

When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an Office.AsyncResult object. The properties of the selected messages, such as the item ID and subject, are returned as an array of SelectedItemDetails objects in the asyncResult.value property. The objects in the array follow the order in which messages were selected.

Returns

void

Remarks

[Api set: Mailbox 1.13]

Minimum permission level: read/write mailbox

Applicable Outlook mode: Compose, Read

Important: This method only applies to messages.

getSelectedItemsAsync(callback)

Gets currently selected messages on which an add-in can activate and perform operations. An add-in can activate on a maximum of 100 messages at a time. To learn more about item multi-select, see Activate your Outlook add-in on multiple messages.

getSelectedItemsAsync(callback: (asyncResult: Office.AsyncResult<SelectedItemDetails[]>) => void): void;

Parameters

callback: (asyncResult: Office.AsyncResult<Office.SelectedItemDetails[]>) => void

When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an Office.AsyncResult object. The properties of the selected messages, such as the item ID and subject, are returned as an array of SelectedItemDetails objects in the asyncResult.value property. The objects in the array follow the order in which messages were selected.

Returns

void

Remarks

[Api set: Mailbox 1.13]

Minimum permission level: read/write mailbox

Applicable Outlook mode: Compose, Read

Important: This method only applies to messages.

getUserIdentityTokenAsync(callback, userContext)

Gets a token identifying the user and the Office Add-in.

The token is returned as a string in the asyncResult.value property.

getUserIdentityTokenAsync(callback: (asyncResult: Office.AsyncResult<string>) => void, userContext?: any): void;

Parameters

callback: (asyncResult: Office.AsyncResult<string>) => void

When the method completes, the function passed in the callback parameter is called with a single parameter of type Office.AsyncResult. The token is returned as a string in the asyncResult.value property. If there was an error, the asyncResult.error and asyncResult.diagnostics properties may provide additional information.

userContext: any

Optional. Any state data that is passed to the asynchronous method.

Returns

void

Remarks

Minimum permission level: read item

Applicable Outlook mode: Compose or Read

Important:

Legacy Exchange Online user identity tokens and callback tokens are no longer supported and are turned off across all Microsoft 365 tenants. If an Outlook add-in requires delegated user access or user identity, we recommend using MSAL (Microsoft Authentication Library) and nested app authentication (NAA). Exchange user identity tokens are still supported for Exchange on-premises.
The getUserIdentityTokenAsync method returns a token that you can use to identify and authenticate the add-in and user with an external system.
This method isn't supported if you load an add-in in an Outlook.com or Gmail mailbox.

Errors:

If your call fails, use the asyncResult.diagnostics property to view details about the error.

GenericTokenError: An internal error has occurred. - In Exchange Online environments, this error occurs when the token can't be retrieved because legacy Exchange tokens for Outlook add-ins are turned off. We recommend using NAA as a single sign-on solution for your add-in.
HTTPRequestFailure: The request has failed. Please look at the diagnostics object for the HTTP error code.
InternalServerError: The Exchange server returned an error. Please look at the diagnostics object for more information. - In Exchange Online environments, this error occurs when the token can't be retrieved because legacy Exchange tokens for Outlook add-ins are turned off. We recommend using NAA as a single sign-on solution for your add-in.
NetworkError: The user is no longer connected to the network. Please check your network connection and try again.

loadItemByIdAsync(itemId, options, callback)

Loads a single mail item by its Exchange Web Services (EWS) ID. Then, gets an object that provides the properties and methods of the loaded item.

loadItemByIdAsync(itemId: string, options: Office.AsyncContextOptions, callback: (asyncResult: Office.AsyncResult<LoadedMessageCompose | LoadedMessageRead>) => void): void;

Parameters

itemId: string

The EWS ID of a mail item.

options: Office.AsyncContextOptions

An object literal that contains the asyncContext property. In this property, provide any object you wish to access in the callback function.

callback: (asyncResult: Office.AsyncResult<Office.LoadedMessageCompose | Office.LoadedMessageRead>) => void

When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an Office.AsyncResult object. A LoadedMessageCompose or LoadedMessageRead object is returned in the asyncResult.value property. This object provides the properties of the item that's currently loaded.

Returns

void

Remarks

[Api set: Mailbox 1.15]

Minimum permission level: read/write mailbox

Applicable Outlook mode: Compose, Read

Important:

This method only applies to messages.
When implementing the item multi-select feature, call Office.context.mailbox.getSelectedItemsAsync to get the item IDs of each selected item, so that they can be loaded one at a time.
Before you implement the loadItemByIdAsync method with the item multi-select feature, determine if you can already access the required properties of the selected item using the Office.context.mailbox.getSelectedItemsAsync call. If you can, you don't need to call loadItemByIdAsync.
Only one mail item can be loaded at a time. When you implement loadItemByIdAsync, you must call unloadAsync after processing the item. This must be done before calling loadItemByIdAsync on another item.
The loadItemByIdAsync method can only be called on messages in the same mailbox.

loadItemByIdAsync(itemId, callback)

Loads a single mail item by its Exchange Web Services (EWS) ID. Then, gets an object that provides the properties and methods of the loaded item.

loadItemByIdAsync(itemId: string, callback: (asyncResult: Office.AsyncResult<LoadedMessageCompose | LoadedMessageRead>) => void): void;

Parameters

itemId: string

The EWS ID of a mail item.

callback: (asyncResult: Office.AsyncResult<Office.LoadedMessageCompose | Office.LoadedMessageRead>) => void

When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an Office.AsyncResult object. A LoadedMessageCompose or LoadedMessageRead object is returned in the asyncResult.value property. This object provides the properties of the item that's currently loaded.

Returns

void

Remarks

[Api set: Mailbox 1.15]

Minimum permission level: read/write mailbox

Applicable Outlook mode: Compose, Read

Important:

This method only applies to messages.
When implementing the item multi-select feature, call Office.context.mailbox.getSelectedItemsAsync to get the item IDs of each selected item, so that they can be loaded one at a time.
Before you implement the loadItemByIdAsync method with the item multi-select feature, determine if you can already access the required properties of the selected item using the Office.context.mailbox.getSelectedItemsAsync call. If you can, you don't need to call loadItemByIdAsync.
Only one mail item can be loaded at a time. When you implement loadItemByIdAsync, you must call unloadAsync after processing the item. This must be done before calling loadItemByIdAsync on another item.
The loadItemByIdAsync method can only be called on messages in the same mailbox.

makeEwsRequestAsync(data, callback, userContext)

Makes an asynchronous request to an Exchange Web Services (EWS) service on the Exchange server that hosts the user's mailbox.

The makeEwsRequestAsync method sends an EWS request on behalf of the add-in to Exchange.

makeEwsRequestAsync(data: any, callback: (asyncResult: Office.AsyncResult<string>) => void, userContext?: any): void;

Parameters

data: any

The EWS request.

callback: (asyncResult: Office.AsyncResult<string>) => void

When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an Office.AsyncResult object. The XML response of the EWS request is provided as a string in the asyncResult.value property. In Outlook on the web, on Windows (new and classic (starting in Version 2303, Build 16225.10000)), and on Mac (starting in Version 16.73 (23042601)), if the response exceeds 5 MB in size, an error message is returned in the asyncResult.error property. In earlier versions of Outlook on Windows (classic) and on Mac, an error message is returned if the response exceeds 1 MB in size.

userContext: any

Optional. Any state data that is passed to the asynchronous method.

Returns

void

Remarks

[Api set: Mailbox 1.1]

Minimum permission level: read/write mailbox

Applicable Outlook mode: Compose or Read

Important:

Legacy Exchange Online user identity tokens and callback tokens are no longer supported and are turned off across all Microsoft 365 tenants. If an Outlook add-in requires delegated user access or user identity, we recommend using MSAL (Microsoft Authentication Library) and nested app authentication (NAA). Exchange user identity tokens are still supported for Exchange on-premises.
To enable the makeEwsRequestAsync method to make EWS requests, the server administrator must set OAuthAuthentication to true on the Client Access Server EWS directory .
Your add-in must have the read/write mailbox permission to use the makeEwsRequestAsync method. For information about using the read/write mailbox permission and the EWS operations that you can call with the makeEwsRequestAsync method, see Specify permissions for mail add-in access to the user's mailbox.
If your add-in needs to access Folder Associated Items or its XML request must specify UTF-8 encoding (\<?xml version="1.0" encoding="utf-8"?\>), it must use Microsoft Graph or REST APIs to access the user's mailbox instead.
This method isn't supported in Outlook on Android or on iOS. For more information on supported APIs in Outlook mobile, see Outlook JavaScript APIs supported in Outlook on mobile devices.
This method isn't supported when the add-in is loaded in a Gmail mailbox.
When you use the makeEwsRequestAsync method in add-ins that run in Outlook versions earlier than Version 15.0.4535.1004, you must set the encoding value to ISO-8859-1 (<?xml version="1.0" encoding="iso-8859-1"?>). To determine the version of an Outlook client, use the mailbox.diagnostics.hostVersion property. You don't need to set the encoding value when your add-in is running in Outlook on the web or new Outlook on Windows. To determine the Outlook client in which your add-in is running, use the mailbox.diagnostics.hostName property.

removeHandlerAsync(eventType, options, callback)

Removes the event handlers for a supported event type. Events are only available in task pane add-ins.

removeHandlerAsync(eventType: Office.EventType | string, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameters

eventType: Office.EventType | string

The event that should revoke the handler.

options: Office.AsyncContextOptions

Provides an option for preserving context data of any type, unchanged, for use in a callback.

callback: (asyncResult: Office.AsyncResult<void>) => void

Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type Office.AsyncResult.

Returns

void

Remarks

[Api set: Mailbox 1.5]

Minimum permission level: read item

Applicable Outlook mode: Compose or Read

Important: The following events are supported on the Mailbox object.

Event	Description	Minimum requirement set
`DragAndDropEvent`	A message or file attachment in the Outlook client window is dragged then dropped into the task pane of an add-in. This event is only supported in Outlook on the web and the new Outlook on Windows.	1.5
`ItemChanged`	A different Outlook item is selected for viewing while the task pane is pinned.	1.5
`OfficeThemeChanged`	The OfficeTheme is changed in Outlook.	1.14
`SelectedItemsChanged`	One or more messages are selected or deselected.	1.13

removeHandlerAsync(eventType, callback)

Removes the event handlers for a supported event type. Events are only available in task pane add-ins.

removeHandlerAsync(eventType: Office.EventType | string, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameters

eventType: Office.EventType | string

The event that should revoke the handler.

callback: (asyncResult: Office.AsyncResult<void>) => void

Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type Office.AsyncResult.

Returns

void

Remarks

[Api set: Mailbox 1.5]

Minimum permission level: read item

Applicable Outlook mode: Compose or Read

Important: The following events are supported on the Mailbox object.

Event	Description	Minimum requirement set
`DragAndDropEvent`	A message or file attachment in the Outlook client window is dragged then dropped into the task pane of an add-in. This event is only supported in Outlook on the web and the new Outlook on Windows.	1.5
`ItemChanged`	A different Outlook item is selected for viewing while the task pane is pinned.	1.5
`OfficeThemeChanged`	The OfficeTheme is changed in Outlook.	1.14
`SelectedItemsChanged`	One or more messages are selected or deselected.	1.13

Remarks

Properties

Methods

Property Details

diagnostics

Property Value

Remarks

ewsUrl

Property Value

Remarks

item

Property Value

masterCategories

Property Value

Remarks

restUrl

Property Value

Remarks

userProfile

Property Value

Method Details

addHandlerAsync(eventType, handler, options, callback)

Parameters

Returns

Remarks

addHandlerAsync(eventType, handler, callback)

Parameters

Returns

Remarks

convertToEwsId(id, restVersion)

Parameters

Returns

Remarks

convertToLocalClientTime(timeValue)

Parameters

Returns

Remarks

convertToRestId(id, restVersion)

Parameters

Returns

Remarks

convertToUtcClientTime(input)

Parameters

Returns

Remarks

displayAppointmentForm(itemId)

Parameters

Returns

Remarks

displayAppointmentFormAsync(itemId, options, callback)

Parameters

Returns

Remarks

displayAppointmentFormAsync(itemId, callback)

Parameters

Returns

Remarks

displayMessageForm(itemId)

Parameters

Returns

Remarks

displayMessageFormAsync(itemId, options, callback)

Parameters

Returns

Remarks

displayMessageFormAsync(itemId, callback)

Parameters

Returns

Remarks

displayNewAppointmentForm(parameters)

Parameters

Returns

Remarks

displayNewAppointmentFormAsync(parameters, options, callback)

Parameters

Returns

Remarks

displayNewAppointmentFormAsync(parameters, callback)

Parameters