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.

Contains the following members:

  • hostName (string): A string that represents the name of the host application. It should be one of the following values: Outlook, OutlookWebApp, OutlookIOS, or OutlookAndroid. Note: The "Outlook" value is returned for Outlook on desktop clients (i.e., Windows and Mac).

  • hostVersion (string): A string that represents the version of either the host application or the Exchange Server (e.g., "15.0.468.0"). If the mail add-in is running in Outlook on desktop or mobile clients, the hostVersion property returns the version of the host application, Outlook. In Outlook on the web, the property returns the version of the Exchange Server.

  • OWAView (MailboxEnums.OWAView or string): An enum (or string literal) that represents the current view of Outlook on the web. If the host application is not Outlook on the web, then accessing this property results in undefined. Outlook on the web has three views (OneColumn - displayed when the screen is narrow, TwoColumns - displayed when the screen is wider, and ThreeColumns - displayed when the screen is wide) that correspond to the width of the screen and the window, and the number of columns that can be displayed.

More information is under Office.Diagnostics.

ewsUrl

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

Your app must have the ReadItem 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 ReadWriteItem permissions to call the saveAsync method.

Note: This member is not supported in Outlook on iOS or Android.

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: 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.

Your app must have the ReadItem 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 app must have ReadWriteItem 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

Methods

addHandlerAsync(eventType, handler, options, callback)

Adds an event handler for a supported event. Note: Events are only available with task pane implementation.

For supported events, refer to the Mailbox object model events section.

addHandlerAsync(eventType, handler, callback)

Adds an event handler for a supported event. Note: Events are only available with task pane implementation.

For supported events, refer to the Mailbox object model events section.

convertToEwsId(itemId, restVersion)

Converts an item ID formatted for REST into EWS format.

Item IDs retrieved via a REST API (such as the Outlook Mail API or the Microsoft Graph) use a different format than the format used by Exchange Web Services (EWS). The convertToEwsId method converts a REST-formatted ID into the proper format for EWS.

Note: This method is not supported in Outlook on iOS or Android.

convertToLocalClientTime(timeValue)

Gets a dictionary containing time information in local client time.

The dates and times used by a mail app for Outlook on the web or desktop clients can use different time zones. Outlook uses the client computer time zone; Outlook on the web uses 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.

If the mail app is running in Outlook on desktop clients, the convertToLocalClientTime method will return a dictionary object with the values set to the client computer time zone. If the mail app is running in Outlook on the web, the convertToLocalClientTime method will return a dictionary object with the values set to the time zone specified in the EAC.

convertToRestId(itemId, restVersion)

Converts an item ID formatted for EWS into REST format.

Note: This method is not supported in Outlook on iOS or Android.

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 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, 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 is not supported in Outlook on iOS or Android.

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, 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 is not supported in Outlook on iOS or 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, 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 is not supported in Outlook on iOS or Android.

displayMessageForm(itemId)

Displays an existing message.

The displayMessageForm 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, 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.

Do not 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.

Note: This method is not supported in Outlook on iOS or Android.

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, 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.

Do not 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 is not supported in Outlook on iOS or 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, 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.

Do not 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 is not supported in Outlook on iOS or 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, 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 the Outlook rich client and Outlook RT, 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 is not supported in Outlook on iOS or Android.

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, 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 the Outlook rich client and Outlook RT, 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 is not supported in Outlook on iOS or 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, 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 the Outlook rich client and Outlook RT, 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 is not supported in Outlook on iOS or 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.

Calling the getCallbackTokenAsync method in read mode requires a minimum permission level of ReadItem.

Calling the getCallbackTokenAsync method in compose mode requires you to have saved the item. The saveAsync method requires a minimum permission level of ReadWriteItem.

Important: 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 will not 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 ReadWriteMailbox permission in its manifest. If the ReadWriteMailbox 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 will not 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 a third-party system. The third-party 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.

Note: It is recommended that add-ins use the REST APIs instead of Exchange Web Services whenever possible.

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.

You can pass both the token and either an attachment identifier or item identifier to a third-party system. The third-party 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 ReadItem.

Calling the getCallbackTokenAsync method in compose mode requires you to have saved the item. The saveAsync method requires a minimum permission level of ReadWriteItem.

Important: For guidance on delegate or shared scenarios, see the shared folders and shared mailbox article.

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.

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.

In these cases, add-ins should use REST APIs to access the user's mailbox instead.

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

You cannot request Folder Associated Items with the makeEwsRequestAsync method.

The XML request must specify UTF-8 encoding: \<?xml version="1.0" encoding="utf-8"?\>.

Your add-in must have the ReadWriteMailbox permission to use the makeEwsRequestAsync method. For information about using the ReadWriteMailbox 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.

The XML result of the EWS call is provided as a string in the asyncResult.value property. If the result exceeds 1 MB in size, an error message is returned instead.

Note: This method is not supported in the following scenarios:

  • In Outlook on iOS or Android.

  • When the add-in is loaded in a Gmail mailbox.

Note: The server administrator must set OAuthAuthentication to true on the Client Access Server EWS directory to enable the makeEwsRequestAsync method to make EWS requests.

Version differences

When you use the makeEwsRequestAsync method in mail apps running in Outlook versions earlier than version 15.0.4535.1004, you should set the encoding value to ISO-8859-1.

<?xml version="1.0" encoding="iso-8859-1"?>

You do not need to set the encoding value when your mail app is running in Outlook on the web. You can determine whether your mail app is running in Outlook or Outlook on the web by using the mailbox.diagnostics.hostName property. You can determine what version of Outlook is running by using the mailbox.diagnostics.hostVersion property.

removeHandlerAsync(eventType, options, callback)

Removes the event handlers for a supported event type. Note: Events are only available with task pane implementation.

For supported events, refer to the Mailbox object model events section.

removeHandlerAsync(eventType, callback)

Removes the event handlers for a supported event type. Note: Events are only available with task pane implementation.

For supported events, refer to the Mailbox object model events section.

Property Details

diagnostics

Provides diagnostic information to an Outlook add-in.

Contains the following members:

  • hostName (string): A string that represents the name of the host application. It should be one of the following values: Outlook, OutlookWebApp, OutlookIOS, or OutlookAndroid. Note: The "Outlook" value is returned for Outlook on desktop clients (i.e., Windows and Mac).

  • hostVersion (string): A string that represents the version of either the host application or the Exchange Server (e.g., "15.0.468.0"). If the mail add-in is running in Outlook on desktop or mobile clients, the hostVersion property returns the version of the host application, Outlook. In Outlook on the web, the property returns the version of the Exchange Server.

  • OWAView (MailboxEnums.OWAView or string): An enum (or string literal) that represents the current view of Outlook on the web. If the host application is not Outlook on the web, then accessing this property results in undefined. Outlook on the web has three views (OneColumn - displayed when the screen is narrow, TwoColumns - displayed when the screen is wider, and ThreeColumns - displayed when the screen is wide) that correspond to the width of the screen and the window, and the number of columns that can be displayed.

More information is under Office.Diagnostics.

diagnostics: Diagnostics;

Property Value

Remarks

Minimum permission level: ReadItem

Applicable Outlook mode: Compose or Read

ewsUrl

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

Your app must have the ReadItem 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 ReadWriteItem permissions to call the saveAsync method.

Note: This member is not supported in Outlook on iOS or Android.

ewsUrl: string;

Property Value

string

Remarks

Minimum permission level: ReadItem

Applicable Outlook mode: Compose or Read

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.

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/85-tokens-and-service-calls/ids-and-urls.yaml
console.log("EWS URL: " + Office.context.mailbox.ewsUrl);
var ewsId = Office.context.mailbox.item.itemId;
console.log("EWS item ID: " + Office.context.mailbox.item.itemId);

console.log("REST URL: " + Office.context.mailbox.restUrl);
var restId = Office.context.mailbox.convertToRestId(ewsId, Office.MailboxEnums.RestVersion.v2_0);
console.log("REST item ID: " + restId);

var ewsId2 = Office.context.mailbox.convertToEwsId(restId, Office.MailboxEnums.RestVersion.v2_0);
console.log("EWS ID (from REST ID): " + ewsId2);

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: 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

masterCategories

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

masterCategories: MasterCategories;

Property Value

Remarks

[ API set: Mailbox 1.8 ]

Minimum permission level: ReadWriteMailbox

Applicable Outlook mode: Compose or Read

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/45-categories/work-with-master-categories.yaml
Office.context.mailbox.masterCategories.getAsync(function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    var categories = asyncResult.value;
    if (categories && categories.length > 0) {
      console.log("Master categories:");
      console.log(JSON.stringify(categories));
    } else {
      console.log("There are no categories in the master list.");
    }
  } else {
    console.error(asyncResult.error);
  }
});
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/45-categories/work-with-master-categories.yaml
var masterCategoriesToAdd = [
  {
    displayName: "TestCategory",
    color: Office.MailboxEnums.CategoryColor.Preset0
  }
];

Office.context.mailbox.masterCategories.addAsync(masterCategoriesToAdd, function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    console.log("Successfully added categories to master list");
  } else {
    console.log("masterCategories.addAsync call failed with error: " + asyncResult.error.message);
  }
});
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/45-categories/work-with-master-categories.yaml
var masterCategoriesToRemove = ["TestCategory"];

Office.context.mailbox.masterCategories.removeAsync(masterCategoriesToRemove, function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    console.log("Successfully removed categories from master list");
  } else {
    console.log("masterCategories.removeAsync call failed with error: " + asyncResult.error.message);
  }
});

restUrl

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

Your app must have the ReadItem 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 app must have ReadWriteItem 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.

restUrl: string;

Property Value

string

Remarks

[ API set: Mailbox 1.5 ]

Minimum permission level: ReadItem

Applicable Outlook mode: Compose or Read

The restUrl value can be used to make REST API calls to the user's mailbox.

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/85-tokens-and-service-calls/basic-rest-cors.yaml
Office.context.mailbox.getCallbackTokenAsync({ isRest: true }, function (result) {
    var ewsId = Office.context.mailbox.item.itemId;
    var token = result.value;
    var restId = Office.context.mailbox.convertToRestId(ewsId, Office.MailboxEnums.RestVersion.v2_0);
    var getMessageUrl = Office.context.mailbox.restUrl + '/v2.0/me/messages/' + restId;
            
    var xhr = new XMLHttpRequest();
    xhr.open('GET', getMessageUrl);
    xhr.setRequestHeader("Authorization", "Bearer " + token);
    xhr.onload = function (e) {
        console.log(this.response);
    }
    xhr.send();
});
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/85-tokens-and-service-calls/ids-and-urls.yaml
console.log("EWS URL: " + Office.context.mailbox.ewsUrl);
var ewsId = Office.context.mailbox.item.itemId;
console.log("EWS item ID: " + Office.context.mailbox.item.itemId);

console.log("REST URL: " + Office.context.mailbox.restUrl);
var restId = Office.context.mailbox.convertToRestId(ewsId, Office.MailboxEnums.RestVersion.v2_0);
console.log("REST item ID: " + restId);

var ewsId2 = Office.context.mailbox.convertToEwsId(restId, Office.MailboxEnums.RestVersion.v2_0);
console.log("EWS ID (from REST ID): " + ewsId2);

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

Method Details

addHandlerAsync(eventType, handler, options, callback)

Adds an event handler for a supported event. Note: Events are only available with task pane implementation.

For supported events, refer to the Mailbox object model events section.

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: ReadItem

Applicable Outlook mode: Compose or Read

Examples

Office.initialize = function (reason) {
    $(document).ready(function () {
        Office.context.mailbox.addHandlerAsync(
            Office.EventType.ItemChanged,
            loadNewItem,
            function (result) {
                if (result.status === Office.AsyncResultStatus.Failed) {
                    // Handle error.
                }
            });
    });
};

function loadNewItem(eventArgs) {
    var item = Office.context.mailbox.item;

    // Check that item is not null.
    if (item !== null) {
        // Work with item, e.g., define and call function that
        // loads the properties of the newly selected item.
        loadProps(item);
    }
}

addHandlerAsync(eventType, handler, callback)

Adds an event handler for a supported event. Note: Events are only available with task pane implementation.

For supported events, refer to the Mailbox object model events section.

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: ReadItem

Applicable Outlook mode: Compose or Read

convertToEwsId(itemId, restVersion)

Converts an item ID formatted for REST into EWS format.

Item IDs retrieved via a REST API (such as the Outlook Mail API or the Microsoft Graph) use a different format than the format used by Exchange Web Services (EWS). The convertToEwsId method converts a REST-formatted ID into the proper format for EWS.

Note: This method is not supported in Outlook on iOS or Android.

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

Parameters

itemId

string

An item ID formatted for the Outlook REST APIs.

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

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/85-tokens-and-service-calls/ids-and-urls.yaml
console.log("EWS URL: " + Office.context.mailbox.ewsUrl);
var ewsId = Office.context.mailbox.item.itemId;
console.log("EWS item ID: " + Office.context.mailbox.item.itemId);

console.log("REST URL: " + Office.context.mailbox.restUrl);
var restId = Office.context.mailbox.convertToRestId(ewsId, Office.MailboxEnums.RestVersion.v2_0);
console.log("REST item ID: " + restId);

var ewsId2 = Office.context.mailbox.convertToEwsId(restId, Office.MailboxEnums.RestVersion.v2_0);
console.log("EWS ID (from REST ID): " + ewsId2);

convertToLocalClientTime(timeValue)

Gets a dictionary containing time information in local client time.

The dates and times used by a mail app for Outlook on the web or desktop clients can use different time zones. Outlook uses the client computer time zone; Outlook on the web uses 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.

If the mail app is running in Outlook on desktop clients, the convertToLocalClientTime method will return a dictionary object with the values set to the client computer time zone. If the mail app is running in Outlook on the web, the convertToLocalClientTime method will return 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

Remarks

Minimum permission level: ReadItem

Applicable Outlook mode: Compose or Read

convertToRestId(itemId, restVersion)

Converts an item ID formatted for EWS into REST format.

Note: This method is not supported in Outlook on iOS or Android.

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

Parameters

itemId

string

An item ID formatted for Exchange Web Services (EWS)

restVersion

Office.MailboxEnums.RestVersion | string

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

Returns

string

Remarks

[ API set: Mailbox 1.3 ]

Minimum permission level: Restricted

Applicable Outlook mode: Compose or Read

Item IDs retrieved via EWS or via the itemId property use a different format than the format used by REST APIs (such as the Outlook Mail API or the Microsoft Graph. The convertToRestId method converts an EWS-formatted ID into the proper format for REST.

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/85-tokens-and-service-calls/basic-rest-cors.yaml
Office.context.mailbox.getCallbackTokenAsync({ isRest: true }, function (result) {
    var ewsId = Office.context.mailbox.item.itemId;
    var token = result.value;
    var restId = Office.context.mailbox.convertToRestId(ewsId, Office.MailboxEnums.RestVersion.v2_0);
    var getMessageUrl = Office.context.mailbox.restUrl + '/v2.0/me/messages/' + restId;
            
    var xhr = new XMLHttpRequest();
    xhr.open('GET', getMessageUrl);
    xhr.setRequestHeader("Authorization", "Bearer " + token);
    xhr.onload = function (e) {
        console.log(this.response);
    }
    xhr.send();
});
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/85-tokens-and-service-calls/ids-and-urls.yaml
console.log("EWS URL: " + Office.context.mailbox.ewsUrl);
var ewsId = Office.context.mailbox.item.itemId;
console.log("EWS item ID: " + Office.context.mailbox.item.itemId);

console.log("REST URL: " + Office.context.mailbox.restUrl);
var restId = Office.context.mailbox.convertToRestId(ewsId, Office.MailboxEnums.RestVersion.v2_0);
console.log("REST item ID: " + restId);

var ewsId2 = Office.context.mailbox.convertToEwsId(restId, Office.MailboxEnums.RestVersion.v2_0);
console.log("EWS ID (from REST ID): " + ewsId2);

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: ReadItem

Applicable Outlook mode: Compose or Read

Examples

// Represents 3:37 PM PDT on Monday, August 26, 2019.
var input = {
    date: 26,
    hours: 15,
    milliseconds: 2,
    minutes: 37,
    month: 7,
    seconds: 2,
    timezoneOffset: -420,
    year: 2019
};

// result should be a Date object.
var result = Office.context.mailbox.convertToUtcClientTime(input);

// Output should be "2019-08-26T22:37:02.002Z".
console.log(result.toISOString());

displayAppointmentForm(itemId)

Displays an existing calendar appointment.

The displayAppointmentForm 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, 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 is not supported in Outlook on iOS or Android.

displayAppointmentForm(itemId: string): void;

Parameters

itemId

string

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

Returns

void

Remarks

Minimum permission level: ReadItem

Applicable Outlook mode: Compose or Read

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/55-display-items/display-existing-appointment.yaml
var itemId = $("#itemId").val();
Office.context.mailbox.displayAppointmentForm(itemId);

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, 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 is not supported in Outlook on iOS or 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 method.

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: ReadItem

Applicable Outlook mode: Compose or Read

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/55-display-items/display-existing-appointment.yaml
var itemId = $("#itemId").val();

// The async version will return error 9049 if the item is not found.
// The async version is only available starting with requirement set 1.9.
Office.context.mailbox.displayAppointmentFormAsync(itemId, function(asyncResult) {
  console.log("Result: " + JSON.stringify(asyncResult));
});

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, 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 is not supported in Outlook on iOS or 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: ReadItem

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 or in a dialog box on mobile devices.

In Outlook on the web, 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.

Do not 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.

Note: This method is not supported in Outlook on iOS or Android.

displayMessageForm(itemId: string): void;

Parameters

itemId

string

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

Returns

void

Remarks

Minimum permission level: ReadItem

Applicable Outlook mode: Compose or Read

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/55-display-items/display-existing-message.yaml
var itemId = $("#itemId").val();
Office.context.mailbox.displayMessageForm(itemId);

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, 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.

Do not 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 is not supported in Outlook on iOS or 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 method.

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: ReadItem

Applicable Outlook mode: Compose or Read

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/55-display-items/display-existing-message.yaml
var itemId = $("#itemId").val();

// The async version will return error 9049 if the item is not found.
// The async version is only available starting with requirement set 1.9.
Office.context.mailbox.displayMessageFormAsync(itemId, function (asyncResult) {
 console.log("Result: " + JSON.stringify(asyncResult));
});

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, 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.

Do not 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 is not supported in Outlook on iOS or 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: ReadItem

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, 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 the Outlook rich client and Outlook RT, 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 is not supported in Outlook on iOS or Android.

displayNewAppointmentForm(parameters: AppointmentForm): void;

Parameters

parameters
Office.AppointmentForm

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

Returns

void

Remarks

Minimum permission level: ReadItem

Applicable Outlook mode: Read

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/55-display-items/display-new-appointment.yaml
var start = new Date();
var end = new Date();
end.setHours(start.getHours() + 1);

Office.context.mailbox.displayNewAppointmentForm({
  requiredAttendees: ["bob@contoso.com"],
  optionalAttendees: ["sam@contoso.com"],
  start: start,
  end: end,
  location: "Home",
  subject: "meeting",
  resources: ["projector@contoso.com"],
  body: "Hello World!"
});

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, 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 the Outlook rich client and Outlook RT, 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 is not supported in Outlook on iOS or 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 method.

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: ReadItem

Applicable Outlook mode: Read

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/55-display-items/display-new-appointment.yaml
var start = new Date();
var end = new Date();
end.setHours(start.getHours() + 1);

// The async version is only available starting with requirement set 1.9,
// and provides a callback when the new appointment form has been created.
Office.context.mailbox.displayNewAppointmentFormAsync(
  {
    requiredAttendees: ["bob@contoso.com"],
    optionalAttendees: ["sam@contoso.com"],
    start: start,
    end: end,
    location: "Home",
    subject: "meeting",
    resources: ["projector@contoso.com"],
    body: "Hello World!"
  },
  function(asyncResult) {
    console.log(JSON.stringify(asyncResult));
  }
);

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, 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 the Outlook rich client and Outlook RT, 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 is not supported in Outlook on iOS or 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: ReadItem

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: any): void;

Parameters

parameters

any

A dictionary containing all values to be filled in for the user in the new form. All parameters are optional.

toRecipients: An array of strings containing the email addresses or an array containing an EmailAddressDetails object for each of the recipients on the To line. The array is limited to a maximum of 100 entries.

ccRecipients: An array of strings containing the email addresses or an array containing an EmailAddressDetails object for each of the recipients on the Cc line. The array is limited to a maximum of 100 entries.

bccRecipients: An array of strings containing the email addresses or an array containing an EmailAddressDetails object for each of the recipients on the Bcc line. The array is limited to a maximum of 100 entries.

subject: A string containing the subject of the message. The string is limited to a maximum of 255 characters.

htmlBody: The HTML body of the message. The body content is limited to a maximum size of 32 KB.

attachments: An array of JSON objects that are either file or item attachments.

attachments.type: Indicates the type of attachment. Must be file for a file attachment or item for an item attachment.

attachments.name: A string that contains the name of the attachment, up to 255 characters in length.

attachments.url: Only used if type is set to file. The URI of the location for the file.

attachments.isInline: Only used if type is set to file. If true, indicates that the attachment will be shown inline in the message body, and should not be displayed in the attachment list.

attachments.itemId: Only used if type is set to item. The EWS item id of the existing e-mail you want to attach to the new message. This is a string up to 100 characters.

Returns

void

Remarks

[ API set: Mailbox 1.6 ]

Minimum permission level: ReadItem

Applicable Outlook mode: Read

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/55-display-items/display-new-message.yaml
Office.context.mailbox.displayNewMessageForm({
  toRecipients: Office.context.mailbox.item.to, // Copies the To line from current item
  ccRecipients: ["sam@contoso.com"],
  subject: "Outlook add-ins are cool!",
  htmlBody: 'Hello <b>World</b>!<br/><img src="cid:image.png"></i>',
  attachments: [
    {
      type: "file",
      name: "image.png",
      url: "http://www.cutestpaw.com/wp-content/uploads/2011/11/Cute-Black-Dogs-s.jpg",
      isInline: true
    }
  ]
});

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: any, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameters

parameters

any

A dictionary containing all values to be filled in for the user in the new form. All parameters are optional.

toRecipients: An array of strings containing the email addresses or an array containing an EmailAddressDetails object for each of the recipients on the To line. The array is limited to a maximum of 100 entries.

ccRecipients: An array of strings containing the email addresses or an array containing an EmailAddressDetails object for each of the recipients on the Cc line. The array is limited to a maximum of 100 entries.

bccRecipients: An array of strings containing the email addresses or an array containing an EmailAddressDetails object for each of the recipients on the Bcc line. The array is limited to a maximum of 100 entries.

subject: A string containing the subject of the message. The string is limited to a maximum of 255 characters.

htmlBody: The HTML body of the message. The body content is limited to a maximum size of 32 KB.

attachments: An array of JSON objects that are either file or item attachments.

attachments.type: Indicates the type of attachment. Must be file for a file attachment or item for an item attachment.

attachments.name: A string that contains the name of the attachment, up to 255 characters in length.

attachments.url: Only used if type is set to file. The URI of the location for the file.

attachments.isInline: Only used if type is set to file. If true, indicates that the attachment will be shown inline in the message body, and should not be displayed in the attachment list.

attachments.itemId: Only used if type is set to item. The EWS item id of the existing e-mail you want to attach to the new message. This is a string up to 100 characters.

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 method.

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: ReadItem

Applicable Outlook mode: Read

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/55-display-items/display-new-message.yaml
// The async version is only available starting with requirement set 1.9,
// and provides a callback when the new message form has been created.
Office.context.mailbox.displayNewMessageFormAsync(
  {
    toRecipients: Office.context.mailbox.item.to, // Copies the To line from current item
    ccRecipients: ["sam@contoso.com"],
    subject: "Outlook add-ins are cool!",
    htmlBody: 'Hello <b>World</b>!<br/><img src="cid:image.png"></i>',
    attachments: [
      {
        type: "file",
        name: "image.png",
        url: "http://www.cutestpaw.com/wp-content/uploads/2011/11/Cute-Black-Dogs-s.jpg",
        isInline: true
      }
    ]
  },
  function(asyncResult) {
    console.log(JSON.stringify(asyncResult));
  }
);

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: any, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameters

parameters

any

A dictionary containing all values to be filled in for the user in the new form. All parameters are optional.

toRecipients: An array of strings containing the email addresses or an array containing an EmailAddressDetails object for each of the recipients on the To line. The array is limited to a maximum of 100 entries.

ccRecipients: An array of strings containing the email addresses or an array containing an EmailAddressDetails object for each of the recipients on the Cc line. The array is limited to a maximum of 100 entries.

bccRecipients: An array of strings containing the email addresses or an array containing an EmailAddressDetails object for each of the recipients on the Bcc line. The array is limited to a maximum of 100 entries.

subject: A string containing the subject of the message. The string is limited to a maximum of 255 characters.

htmlBody: The HTML body of the message. The body content is limited to a maximum size of 32 KB.

attachments: An array of JSON objects that are either file or item attachments.

attachments.type: Indicates the type of attachment. Must be file for a file attachment or item for an item attachment.

attachments.name: A string that contains the name of the attachment, up to 255 characters in length.

attachments.url: Only used if type is set to file. The URI of the location for the file.

attachments.isInline: Only used if type is set to file. If true, indicates that the attachment will be shown inline in the message body, and should not be displayed in the attachment list.

attachments.itemId: Only used if type is set to item. The EWS item id of the existing e-mail you want to attach to the new message. This is a string up to 100 characters.

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: ReadItem

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.

Calling the getCallbackTokenAsync method in read mode requires a minimum permission level of ReadItem.

Calling the getCallbackTokenAsync method in compose mode requires you to have saved the item. The saveAsync method requires a minimum permission level of ReadWriteItem.

Important: 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 will not 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 ReadWriteMailbox permission in its manifest. If the ReadWriteMailbox 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 will not 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 a third-party system. The third-party 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.

Note: It is recommended that add-ins use the REST APIs instead of Exchange Web Services whenever possible.

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: ReadItem

Applicable Outlook mode: Compose or Read

Errors:

  • 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.

  • NetworkError: The user is no longer connected to the network. Please check your network connection and try again.

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/85-tokens-and-service-calls/basic-rest-cors.yaml
Office.context.mailbox.getCallbackTokenAsync({ isRest: true }, function (result) {
    var ewsId = Office.context.mailbox.item.itemId;
    var token = result.value;
    var restId = Office.context.mailbox.convertToRestId(ewsId, Office.MailboxEnums.RestVersion.v2_0);
    var getMessageUrl = Office.context.mailbox.restUrl + '/v2.0/me/messages/' + restId;
            
    var xhr = new XMLHttpRequest();
    xhr.open('GET', getMessageUrl);
    xhr.setRequestHeader("Authorization", "Bearer " + token);
    xhr.onload = function (e) {
        console.log(this.response);
    }
    xhr.send();
});

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.

You can pass both the token and either an attachment identifier or item identifier to a third-party system. The third-party 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 ReadItem.

Calling the getCallbackTokenAsync method in compose mode requires you to have saved the item. The saveAsync method requires a minimum permission level of ReadWriteItem.

Important: For guidance on delegate or shared scenarios, see the shared folders and shared mailbox article.

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: ReadItem

Applicable Outlook mode: Compose or Read

Errors:

  • 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.

  • NetworkError: The user is no longer connected to the network. Please check your network connection and try again.

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/85-tokens-and-service-calls/user-callback-token.yaml
Office.context.mailbox.getCallbackTokenAsync(function (result) {
    if (result.status !== Office.AsyncResultStatus.Succeeded) {
        console.error(`Token retrieval failed with message: ${result.error.message}`);
    } else {
        console.log(result.value);
    }
});

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: ReadItem

Applicable Outlook mode: Compose or Read

The getUserIdentityTokenAsync method returns a token that you can use to identify and authenticate the add-in and user with a third-party system.

Errors:

  • 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.

  • NetworkError: The user is no longer connected to the network. Please check your network connection and try again.

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/85-tokens-and-service-calls/user-identity-token.yaml
Office.context.mailbox.getUserIdentityTokenAsync(function (result) {
    if (result.status !== Office.AsyncResultStatus.Succeeded) {
        console.error(`Token retrieval failed with message: ${result.error.message}`);
    } else {
        console.log(result.value);
    }
});

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.

In these cases, add-ins should use REST APIs to access the user's mailbox instead.

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

You cannot request Folder Associated Items with the makeEwsRequestAsync method.

The XML request must specify UTF-8 encoding: \<?xml version="1.0" encoding="utf-8"?\>.

Your add-in must have the ReadWriteMailbox permission to use the makeEwsRequestAsync method. For information about using the ReadWriteMailbox 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.

The XML result of the EWS call is provided as a string in the asyncResult.value property. If the result exceeds 1 MB in size, an error message is returned instead.

Note: This method is not supported in the following scenarios:

  • In Outlook on iOS or Android.

  • When the add-in is loaded in a Gmail mailbox.

Note: The server administrator must set OAuthAuthentication to true on the Client Access Server EWS directory to enable the makeEwsRequestAsync method to make EWS requests.

Version differences

When you use the makeEwsRequestAsync method in mail apps running in Outlook versions earlier than version 15.0.4535.1004, you should set the encoding value to ISO-8859-1.

<?xml version="1.0" encoding="iso-8859-1"?>

You do not need to set the encoding value when your mail app is running in Outlook on the web. You can determine whether your mail app is running in Outlook or Outlook on the web by using the mailbox.diagnostics.hostName property. You can determine what version of Outlook is running by using the mailbox.diagnostics.hostVersion property.

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 of type Office.AsyncResult. The value property of the result is the XML of the EWS request provided as a string. If the result exceeds 1 MB in size, an error message is returned instead.

userContext

any

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

Returns

void

Remarks

Minimum permission level: ReadWriteMailbox

Applicable Outlook mode: Compose or Read

Examples

function getSubjectRequest(id) {
    // Return a GetItem operation request for the subject of the specified item.
    var request =
        '<?xml version="1.0" encoding="utf-8"?>' +
        '<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"' +
        '               xmlns:xsd="http://www.w3.org/2001/XMLSchema"' +
        '               xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"' +
        '               xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types">' +
        '  <soap:Header>' +
        '    <RequestServerVersion Version="Exchange2013" xmlns="http://schemas.microsoft.com/exchange/services/2006/types" soap:mustUnderstand="0" />' +
        '  </soap:Header>' +
        '  <soap:Body>' +
        '    <GetItem xmlns="http://schemas.microsoft.com/exchange/services/2006/messages">' +
        '      <ItemShape>' +
        '        <t:BaseShape>IdOnly</t:BaseShape>' +
        '        <t:AdditionalProperties>' +
        '            <t:FieldURI FieldURI="item:Subject"/>' +
        '        </t:AdditionalProperties>' +
        '      </ItemShape>' +
        '      <ItemIds><t:ItemId Id="' + id + '"/></ItemIds>' +
        '    </GetItem>' +
        '  </soap:Body>' +
        '</soap:Envelope>';

    return request;
}

function sendRequest() {
    // Create a local variable that contains the mailbox.
    Office.context.mailbox.makeEwsRequestAsync(
        getSubjectRequest(mailbox.item.itemId), callback);
}

function callback(asyncResult)  {
    var result = asyncResult.value;
    var context = asyncResult.asyncContext;

    // Process the returned response here.
}
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/85-tokens-and-service-calls/make-ews-request-async.yaml
var ewsId = Office.context.mailbox.item.itemId;
var request = '<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages" xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">' +
    '  <soap:Header><t:RequestServerVersion Version="Exchange2013" /></soap:Header>' +
    '  <soap:Body>' +
    '    <m:GetItem>' +
    '      <m:ItemShape>' +
    '        <t:BaseShape>IdOnly</t:BaseShape>' +
    '      </m:ItemShape >' +
    '      <m:ItemIds>' +
    '        <t:ItemId Id="' + ewsId + '" />' +
    '      </m:ItemIds>' +
    '    </m:GetItem>' +
    '  </soap:Body>' +
    '</soap:Envelope>';

Office.context.mailbox.makeEwsRequestAsync(request, function (result) {
    console.log(result);
});
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/85-tokens-and-service-calls/send-message-using-make-ews-request-async.yaml
var request = '<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages" xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">'+
    '  <soap:Header><t:RequestServerVersion Version="Exchange2010" /></soap:Header>'+
    '  <soap:Body>'+
    '    <m:CreateItem MessageDisposition="SendAndSaveCopy">'+
    '      <m:SavedItemFolderId><t:DistinguishedFolderId Id="sentitems" /></m:SavedItemFolderId>'+
    '      <m:Items>'+
    '        <t:Message>'+
    '          <t:Subject>Hello, Outlook!</t:Subject>'+
    '          <t:Body BodyType="HTML">This message was sent from a ScriptLab code sample, used from ' + Office.context.mailbox.diagnostics.hostName + ', version ' + Office.context.mailbox.diagnostics.hostVersion + '!</t:Body>'+
    '          <t:ToRecipients>'+
    '            <t:Mailbox><t:EmailAddress>' + Office.context.mailbox.userProfile.emailAddress + '</t:EmailAddress></t:Mailbox>'+
    '          </t:ToRecipients>'+
    '        </t:Message>'+
    '      </m:Items>'+
    '    </m:CreateItem>'+
    '  </soap:Body>'+
    '</soap:Envelope>';

Office.context.mailbox.makeEwsRequestAsync(request, function (result) {
    console.log(result);
});

removeHandlerAsync(eventType, options, callback)

Removes the event handlers for a supported event type. Note: Events are only available with task pane implementation.

For supported events, refer to the Mailbox object model events section.

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: ReadItem

Applicable Outlook mode: Compose or Read

removeHandlerAsync(eventType, callback)

Removes the event handlers for a supported event type. Note: Events are only available with task pane implementation.

For supported events, refer to the Mailbox object model events section.

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: ReadItem

Applicable Outlook mode: Compose or Read