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.
More information is under Office.Diagnostics. |
ews |
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: |
master |
Gets an object that provides methods to manage the categories master list associated with a mailbox. |
rest |
Gets the URL of the REST endpoint for this email account. Your app must have the read item permission specified in its manifest to call the In compose mode you must call the However, in delegate or shared scenarios, you should instead use the |
user |
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
add |
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. |
add |
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. |
convert |
Converts a supported ID into the Exchange Web Services (EWS) format. |
convert |
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 |
convert |
Converts a supported ID into REST format. |
convert |
Gets a The |
display |
Displays an existing calendar appointment. The 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. |
display |
Displays an existing calendar appointment. The 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. |
display |
Displays an existing calendar appointment. The 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. |
display |
Displays an existing message. The 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. |
display |
Displays an existing message. The 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 Note: This method isn't supported in Outlook on iOS or on Android. |
display |
Displays an existing message. The 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 Note: This method isn't supported in Outlook on iOS or on Android. |
display |
Displays a form for creating a new calendar appointment. The 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 the Outlook rich client and Outlook RT, if you specify any attendees or resources in the If any of the parameters exceed the specified size limits, or if an unknown parameter name is specified, an exception is thrown. |
display |
Displays a form for creating a new calendar appointment. The 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 the Outlook rich client and Outlook RT, if you specify any attendees or resources in the 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. |
display |
Displays a form for creating a new calendar appointment. The 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 the Outlook rich client and Outlook RT, if you specify any attendees or resources in the 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. |
display |
Displays a form for creating a new message. The If any of the parameters exceed the specified size limits, or if an unknown parameter name is specified, an exception is thrown. |
display |
Displays a form for creating a new message. The If any of the parameters exceed the specified size limits, or if an unknown parameter name is specified, an exception is thrown. |
display |
Displays a form for creating a new message. The If any of the parameters exceed the specified size limits, or if an unknown parameter name is specified, an exception is thrown. |
get |
Gets a string that contains a token used to call REST APIs or Exchange Web Services (EWS). The The token is returned as a string in the |
get |
Gets a string that contains a token used to get an attachment or item from an Exchange Server. The The token is returned as a string in the |
get |
Gets a token identifying the user and the Office Add-in. The token is returned as a string in the |
make |
Makes an asynchronous request to an Exchange Web Services (EWS) service on the Exchange server that hosts the user's mailbox. The |
remove |
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. |
remove |
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 Office application. It should be one of the following values:Outlook
,OutlookWebApp
,OutlookIOS
, orOutlookAndroid
. 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 Office application or the Exchange Server (e.g., "15.0.468.0"). If the mail add-in is running in Outlook on Windows (classic), on Mac, or on mobile devices, thehostVersion
property returns the version of the Outlook client. In Outlook on the web and new Outlook on Windows, 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 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, andThreeColumns
- 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: 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.
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/90-other-item-apis/get-diagnostic-information.yaml
// This function gets a mailbox's diagnostic information, such as Outlook client and version, and logs it to the console.
const diagnostics = Office.context.mailbox.diagnostics;
console.log(`Client application: ${diagnostics.hostName}`);
console.log(`Client version: ${diagnostics.hostVersion}`);
switch (diagnostics.OWAView) {
case undefined:
console.log("Current view (Outlook on the web only): Not applicable. An Outlook desktop client is in use.");
break;
case Office.MailboxEnums.OWAView.OneColumnNarrow:
console.log("Current view (Outlook on the web only): Viewed from an older generation mobile phone");
break;
case Office.MailboxEnums.OWAView.OneColumn:
console.log("Current view (Outlook on the web only): Viewed from a newer generation mobile phone");
break;
case Office.MailboxEnums.OWAView.TwoColumns:
console.log("Current view (Outlook on the web only): Viewed from a tablet");
break;
case Office.MailboxEnums.OWAView.ThreeColumns:
console.log("Current view (Outlook on the web only): Viewed from a desktop computer");
break;
}
ewsUrl
Gets the URL of the Exchange Web Services (EWS) endpoint for this email account.
ewsUrl: string;
Property Value
string
Remarks
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 theewsUrl
member. Your app must have read/write item permissions to call thesaveAsync
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.
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);
const ewsId = Office.context.mailbox.item.itemId;
console.log("EWS item ID: " + Office.context.mailbox.item.itemId);
console.log("REST URL: " + Office.context.mailbox.restUrl);
const restId = Office.context.mailbox.convertToRestId(ewsId, Office.MailboxEnums.RestVersion.v2_0);
console.log("REST item ID: " + restId);
const 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
Minimum permission level: read/write mailbox
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) {
const 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);
}
});
...
const 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);
}
});
...
const 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 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 app 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 delegate access article.
restUrl: string;
Property Value
string
Remarks
Minimum permission level: read item
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) {
const ewsId = Office.context.mailbox.item.itemId;
const token = result.value;
const restId = Office.context.mailbox.convertToRestId(ewsId, Office.MailboxEnums.RestVersion.v2_0);
const getMessageUrl = Office.context.mailbox.restUrl + '/v2.0/me/messages/' + restId;
const xhr = new XMLHttpRequest();
xhr.open('GET', getMessageUrl);
xhr.setRequestHeader("Authorization", "Bearer " + token);
xhr.onload = function (e) {
console.log(this.response);
}
xhr.send();
});
...
console.log("EWS URL: " + Office.context.mailbox.ewsUrl);
const ewsId = Office.context.mailbox.item.itemId;
console.log("EWS item ID: " + Office.context.mailbox.item.itemId);
console.log("REST URL: " + Office.context.mailbox.restUrl);
const restId = Office.context.mailbox.convertToRestId(ewsId, Office.MailboxEnums.RestVersion.v2_0);
console.log("REST item ID: " + restId);
const 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
Minimum permission level: read item
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) {
const 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
Minimum permission level: read item
Applicable Outlook mode: Compose or Read
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
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 a REST API (such as the Outlook Mail API or the 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.
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);
const ewsId = Office.context.mailbox.item.itemId;
console.log("EWS item ID: " + Office.context.mailbox.item.itemId);
console.log("REST URL: " + Office.context.mailbox.restUrl);
const restId = Office.context.mailbox.convertToRestId(ewsId, Office.MailboxEnums.RestVersion.v2_0);
console.log("REST item ID: " + restId);
const 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 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
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
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 the Outlook Mail API or the Microsoft Graph). TheconvertToRestId
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) {
const ewsId = Office.context.mailbox.item.itemId;
const token = result.value;
const restId = Office.context.mailbox.convertToRestId(ewsId, Office.MailboxEnums.RestVersion.v2_0);
const getMessageUrl = Office.context.mailbox.restUrl + '/v2.0/me/messages/' + restId;
const xhr = new XMLHttpRequest();
xhr.open('GET', getMessageUrl);
xhr.setRequestHeader("Authorization", "Bearer " + token);
xhr.onload = function (e) {
console.log(this.response);
}
xhr.send();
});
...
console.log("EWS URL: " + Office.context.mailbox.ewsUrl);
const ewsId = Office.context.mailbox.item.itemId;
console.log("EWS item ID: " + Office.context.mailbox.item.itemId);
console.log("REST URL: " + Office.context.mailbox.restUrl);
const restId = Office.context.mailbox.convertToRestId(ewsId, Office.MailboxEnums.RestVersion.v2_0);
console.log("REST item ID: " + restId);
const 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: read item
Applicable Outlook mode: Compose or Read
Examples
// Represents 3:37 PM PDT on Monday, August 26, 2019.
const input = {
date: 26,
hours: 15,
milliseconds: 2,
minutes: 37,
month: 7,
seconds: 2,
timezoneOffset: -420,
year: 2019
};
// result should be a Date object.
const 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.
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
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.
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/55-display-items/display-existing-appointment.yaml
const 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 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
Minimum permission level: read item
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
const 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 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
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
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 thedisplayAppointmentForm
method to display an existing appointment, anddisplayNewAppointmentForm
to display a form to create a new appointment.
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/55-display-items/display-existing-message.yaml
const 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 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
Minimum permission level: read item
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
const 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 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
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 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.
displayNewAppointmentForm(parameters: AppointmentForm): void;
Parameters
- parameters
- Office.AppointmentForm
An AppointmentForm
describing the new appointment. All properties are optional.
Returns
void
Remarks
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.
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/55-display-items/display-new-appointment.yaml
const start = new Date();
const 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 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 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 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
Minimum permission level: read item
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
const start = new Date();
const 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 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 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 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
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: 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. Important: This link must be publicly accessible, without need for authentication by Exchange Online servers. However, with on-premises Exchange, the link can be accessible on a private network as long as it doesn't need further authentication.
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
Minimum permission level: read item
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: "https://i.imgur.com/9S36xvA.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. Important: This link must be publicly accessible, without need for authentication by Exchange Online servers. However, with on-premises Exchange, the link can be accessible on a private network as long as it doesn't need further authentication.
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 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
Minimum permission level: read item
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: "https://i.imgur.com/9S36xvA.jpg",
isInline: true
}
]
},
(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. Important: This link must be publicly accessible, without need for authentication by Exchange Online servers. However, with on-premises Exchange, the link can be accessible on a private network as long as it doesn't need further authentication.
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
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
Minimum permission level: read item
Applicable Outlook mode: Compose or Read
Important:
In October 2024, legacy Exchange user identity and callback tokens will be turned off by default for all Exchange Online tenants. This is part of Microsoft's Secure Future Initiative, which gives organizations the tools needed to respond to the current threat landscape. Exchange user identity tokens will still work for Exchange on-premises. Nested app authentication is the recommended approach for tokens going forward. For more information, see our blog post and FAQ page.
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 tofalse
.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. ThesaveAsync
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:
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) {
const ewsId = Office.context.mailbox.item.itemId;
const token = result.value;
const restId = Office.context.mailbox.convertToRestId(ewsId, Office.MailboxEnums.RestVersion.v2_0);
const getMessageUrl = Office.context.mailbox.restUrl + '/v2.0/me/messages/' + restId;
const 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.
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:
In October 2024, legacy Exchange user identity and callback tokens will be turned off by default for all Exchange Online tenants. This is part of Microsoft's Secure Future Initiative, which gives organizations the tools needed to respond to the current threat landscape. Exchange user identity tokens will still work for Exchange on-premises. Nested app authentication is the recommended approach for tokens going forward. For more information, see our blog post and FAQ page.
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. ThesaveAsync
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:
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: read item
Applicable Outlook mode: Compose or Read
Important:
In October 2024, legacy Exchange user identity and callback tokens will be turned off by default for all Exchange Online tenants. This is part of Microsoft's Secure Future Initiative, which gives organizations the tools needed to respond to the current threat landscape. Exchange user identity tokens will still work for Exchange on-premises. Nested app authentication is the recommended approach for tokens going forward. For more information, see our blog post and FAQ page.
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:
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.
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
Minimum permission level: read/write mailbox
Applicable Outlook mode: Compose or Read
Important:
In October 2024, legacy Exchange user identity and callback tokens will be turned off by default for all Exchange Online tenants. This is part of Microsoft's Secure Future Initiative, which gives organizations the tools needed to respond to the current threat landscape. Exchange user identity tokens will still work for Exchange on-premises. Nested app authentication is the recommended approach for tokens going forward. For more information, see our blog post and FAQ page.
To enable the
makeEwsRequestAsync
method to make EWS requests, the server administrator must setOAuthAuthentication
totrue
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 themakeEwsRequestAsync
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 themailbox.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 themailbox.diagnostics.hostName
property.
Examples
function getSubjectRequest(id) {
// Return a GetItem operation request for the subject of the specified item.
const 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="Exchange2016" 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) {
const result = asyncResult.value;
const 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/get-icaluid-as-attendee.yaml
const ewsId = Office.context.mailbox.item.itemId;
const 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>AllProperties</t:BaseShape>
</m:ItemShape >
<m:ItemIds>
<t:ItemId Id="${ewsId}" />
</m:ItemIds>
</m:GetItem>
</soap:Body>
</soap:Envelope>`;
Office.context.mailbox.makeEwsRequestAsync(request, (result) => {
if (result.status === Office.AsyncResultStatus.Failed) {
console.error(result.error.message);
return;
}
console.log(getUID(result.value));
});
...
const 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
Minimum permission level: read item
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
Minimum permission level: read item
Applicable Outlook mode: Compose or Read
Office Add-ins