Office.AppointmentRead interface

The appointment attendee mode of Office.context.mailbox.item.

Important: This is an internal Outlook object, not directly exposed through existing interfaces. You should treat this as a mode of Office.context.mailbox.item. For more information, refer to the Object Model page.

Parent interfaces:

Extends

Properties

attachments

Gets the item's attachments as an array.

body

Gets an object that provides methods for manipulating the body of an item.

categories

Gets an object that provides methods for managing the item's categories.

dateTimeCreated

Gets the date and time that an item was created.

dateTimeModified

Gets the date and time that an item was last modified.

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

end

Gets the date and time that the appointment is to end.

The end property is a Date object expressed as a Coordinated Universal Time (UTC) date and time value. You can use the convertToLocalClientTime method to convert the end property value to the client's local date and time.

When you use the Time.setAsync method to set the end time, you should use the convertToUtcClientTime method to convert the local time on the client to UTC for the server.

enhancedLocation

Gets the locations of an appointment.

The enhancedLocation property returns an EnhancedLocation object that allows you to get the set of locations (each represented by a LocationDetails object) associated with the appointment.

isAllDayEvent

Returns a boolean value indicating whether the event is all day.

itemClass

Gets the Exchange Web Services item class of the selected item.

You can create custom message classes that extends a default message class, for example, a custom appointment message class IPM.Appointment.Contoso.

itemId

Gets the Exchange Web Services item identifier for the current item.

The itemId property is not available in compose mode. If an item identifier is required, the saveAsync method can be used to save the item to the store, which will return the item identifier in the asyncResult.value parameter in the callback function.

Note: The identifier returned by the itemId property is the same as the Exchange Web Services item identifier. The itemId property is not identical to the Outlook Entry ID or the ID used by the Outlook REST API. Before making REST API calls using this value, it should be converted using Office.context.mailbox.convertToRestId. For more details, see Use the Outlook REST APIs from an Outlook add-in.

itemType

Gets the type of item that an instance represents.

The itemType property returns one of the ItemType enumeration values, indicating whether the item object instance is a message or an appointment.

location

Gets the location of an appointment.

The location property returns a string that contains the location of the appointment.

normalizedSubject

Gets the subject of an item, with all prefixes removed (including RE: and FWD:).

The normalizedSubject property gets the subject of the item, with any standard prefixes (such as RE: and FW:) that are added by email programs. To get the subject of the item with the prefixes intact, use the subject property.

notificationMessages

Gets the notification messages for an item.

optionalAttendees

Provides access to the optional attendees of an event. The type of object and level of access depend on the mode of the current item.

The optionalAttendees property returns an array that contains an EmailAddressDetails object for each optional attendee to the meeting. Collection size limits:

  • Windows: 500 members

  • Classic Mac UI: 100 members

  • New Mac UI, web browser, Android: No limit

organizer

Gets the meeting organizer's email properties.

recurrence

Gets the recurrence pattern of an appointment. Gets the recurrence pattern of a meeting request.

The recurrence property returns a Recurrence object for recurring appointments or meetings requests if an item is a series or an instance in a series. null is returned for single appointments and meeting requests of single appointments.

Note: Meeting requests have an itemClass value of IPM.Schedule.Meeting.Request.

Note: If the recurrence object is null, this indicates that the object is a single appointment or a meeting request of a single appointment and NOT a part of a series.

requiredAttendees

Provides access to the required attendees of an event. The type of object and level of access depend on the mode of the current item.

The requiredAttendees property returns an array that contains an EmailAddressDetails object for each required attendee to the meeting. Collection size limits:

  • Windows: 500 members

  • Classic Mac UI: 100 members

  • New Mac UI, web browser, Android: No limit

sensitivity

Provides the sensitivity value of the appointment.

seriesId

Gets the ID of the series that an instance belongs to.

In Outlook on the web and desktop clients, the seriesId returns the Exchange Web Services (EWS) ID of the parent (series) item that this item belongs to. However, on iOS and Android, the seriesId returns the REST ID of the parent item.

Note: The identifier returned by the seriesId property is the same as the Exchange Web Services item identifier. The seriesId property is not identical to the Outlook IDs used by the Outlook REST API. Before making REST API calls using this value, it should be converted using Office.context.mailbox.convertToRestId. For more details, see Use the Outlook REST APIs from an Outlook add-in.

The seriesId property returns null for items that do not have parent items such as single appointments, series items, or meeting requests and returns undefined for any other items that are not meeting requests.

start

Gets the date and time that the appointment is to begin.

The start property is a Date object expressed as a Coordinated Universal Time (UTC) date and time value. You can use the convertToLocalClientTime method to convert the value to the client's local date and time.

subject

Gets the description that appears in the subject field of an item.

The subject property gets or sets the entire subject of the item, as sent by the email server.

The subject property returns a string. Use the normalizedSubject property to get the subject minus any leading prefixes such as RE: and FW:.

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 Item 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 Item object model events section.

displayReplyAllForm(formData)

Displays a reply form that includes either the sender and all recipients of the selected message or the organizer and all attendees of the selected appointment.

In Outlook on the web, the reply form is displayed as a pop-out form in the 3-column view and a pop-up form in the 2-column or 1-column view.

If any of the string parameters exceed their limits, displayReplyAllForm throws an exception.

When attachments are specified in the formData.attachments parameter, Outlook attempts to download all attachments and attach them to the reply form. If any attachments fail to be added, an error is shown in the form UI. If this isn't possible, then no error message is thrown.

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

displayReplyAllFormAsync(formData, options, callback)

Displays a reply form that includes either the sender and all recipients of the selected message or the organizer and all attendees of the selected appointment.

In Outlook on the web, the reply form is displayed as a pop-out form in the 3-column view and a pop-up form in the 2-column or 1-column view.

If any of the string parameters exceed their limits, displayReplyAllFormAsync throws an exception.

When attachments are specified in the formData.attachments parameter, Outlook attempts to download all attachments and attach them to the reply form. If any attachments fail to be added, an error is shown in the form UI. If this isn't possible, then no error message is thrown.

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

displayReplyAllFormAsync(formData, callback)

Displays a reply form that includes either the sender and all recipients of the selected message or the organizer and all attendees of the selected appointment.

In Outlook on the web, the reply form is displayed as a pop-out form in the 3-column view and a pop-up form in the 2-column or 1-column view.

If any of the string parameters exceed their limits, displayReplyAllFormAsync throws an exception.

When attachments are specified in the formData.attachments parameter, Outlook attempts to download all attachments and attach them to the reply form. If any attachments fail to be added, an error is shown in the form UI. If this isn't possible, then no error message is thrown.

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

displayReplyForm(formData)

Displays a reply form that includes only the sender of the selected message or the organizer of the selected appointment.

In Outlook on the web, the reply form is displayed as a pop-out form in the 3-column view and a pop-up form in the 2-column or 1-column view.

If any of the string parameters exceed their limits, displayReplyForm throws an exception.

When attachments are specified in the formData.attachments parameter, Outlook attempts to download all attachments and attach them to the reply form. If any attachments fail to be added, an error is shown in the form UI. If this isn't possible, then no error message is thrown.

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

displayReplyFormAsync(formData, options, callback)

Displays a reply form that includes only the sender of the selected message or the organizer of the selected appointment.

In Outlook on the web, the reply form is displayed as a pop-out form in the 3-column view and a pop-up form in the 2-column or 1-column view.

If any of the string parameters exceed their limits, displayReplyFormAsync throws an exception.

When attachments are specified in the formData.attachments parameter, Outlook attempts to download all attachments and attach them to the reply form. If any attachments fail to be added, an error is shown in the form UI. If this isn't possible, then no error message is thrown.

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

displayReplyFormAsync(formData, callback)

Displays a reply form that includes only the sender of the selected message or the organizer of the selected appointment.

In Outlook on the web, the reply form is displayed as a pop-out form in the 3-column view and a pop-up form in the 2-column or 1-column view.

If any of the string parameters exceed their limits, displayReplyFormAsync throws an exception.

When attachments are specified in the formData.attachments parameter, Outlook attempts to download all attachments and attach them to the reply form. If any attachments fail to be added, an error is shown in the form UI. If this isn't possible, then no error message is thrown.

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

getAttachmentContentAsync(attachmentId, options, callback)

Gets an attachment from a message or appointment and returns it as an AttachmentContent object.

The getAttachmentContentAsync method gets the attachment with the specified identifier from the item. As a best practice, you should get the attachment's identifier from an item.attachments call, then in the same session, use that identifier to retrieve the attachment. In Outlook on the web and mobile devices, the attachment identifier is valid only within the same session. A session is over when the user closes the app, or if the user starts composing an inline form then subsequently pops out the form to continue in a separate window.

getAttachmentContentAsync(attachmentId, callback)

Gets an attachment from a message or appointment and returns it as an AttachmentContent object.

The getAttachmentContentAsync method gets the attachment with the specified identifier from the item. As a best practice, you should get the attachment's identifier from an item.attachments call, then in the same session, use that identifier to retrieve the attachment. In Outlook on the web and mobile devices, the attachment identifier is valid only within the same session. A session is over when the user closes the app, or if the user starts composing an inline form then subsequently pops out the form to continue in a separate window.

getEntities()

Gets the entities found in the selected item's body.

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

getEntitiesByType(entityType)

Gets an array of all the entities of the specified entity type found in the selected item's body.

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

getFilteredEntitiesByName(name)

Returns well-known entities in the selected item that pass the named filter defined in the manifest XML file.

The getFilteredEntitiesByName method returns the entities that match the regular expression defined in the ItemHasKnownEntity rule element in the manifest XML file with the specified FilterName element value.

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

getInitializationContextAsync(options, callback)

Gets initialization data passed when the add-in is activated by an actionable message.

getInitializationContextAsync(callback)

Gets initialization data passed when the add-in is activated by an actionable message.

getRegExMatches()

Returns string values in the selected item that match the regular expressions defined in the manifest XML file.

The getRegExMatches method returns the strings that match the regular expression defined in each ItemHasRegularExpressionMatch or ItemHasKnownEntity rule element in the manifest XML file. For an ItemHasRegularExpressionMatch rule, a matching string has to occur in the property of the item that is specified by that rule. The PropertyName simple type defines the supported properties.

If you specify an ItemHasRegularExpressionMatch rule on the body property of an item, the regular expression should further filter the body and should not attempt to return the entire body of the item. Using a regular expression such as .* to obtain the entire body of an item does not always return the expected results. Instead, use the Body.getAsync method to retrieve the entire body.

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

getRegExMatchesByName(name)

Returns string values in the selected item that match the named regular expression defined in the manifest XML file.

The getRegExMatchesByName method returns the strings that match the regular expression defined in the ItemHasRegularExpressionMatch rule element in the manifest XML file with the specified RegExName element value.

If you specify an ItemHasRegularExpressionMatch rule on the body property of an item, the regular expression should further filter the body and should not attempt to return the entire body of the item. Using a regular expression such as .* to obtain the entire body of an item does not always return the expected results.

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

getSelectedEntities()

Gets the entities found in a highlighted match a user has selected. Highlighted matches apply to contextual add-ins.

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

getSelectedRegExMatches()

Returns string values in a highlighted match that match the regular expressions defined in the manifest XML file. Highlighted matches apply to contextual add-ins.

The getSelectedRegExMatches method returns the strings that match the regular expression defined in each ItemHasRegularExpressionMatch or ItemHasKnownEntity rule element in the manifest XML file. For an ItemHasRegularExpressionMatch rule, a matching string has to occur in the property of the item that is specified by that rule. The PropertyName simple type defines the supported properties.

If you specify an ItemHasRegularExpressionMatch rule on the body property of an item, the regular expression should further filter the body and should not attempt to return the entire body of the item. Using a regular expression such as .* to obtain the entire body of an item does not always return the expected results. Instead, use the Body.getAsync method to retrieve the entire body

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

getSharedPropertiesAsync(options, callback)

Gets the properties of an appointment or message in a shared folder or shared mailbox (now in preview).

For more information around using this API, see the shared folders and shared mailbox article.

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

getSharedPropertiesAsync(callback)

Gets the properties of an appointment or message in a shared folder or shared mailbox (now in preview).

For more information around using this API, see the shared folders and shared mailbox article.

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

loadCustomPropertiesAsync(callback, userContext)

Asynchronously loads custom properties for this add-in on the selected item.

Custom properties are stored as key/value pairs on a per-app, per-item basis. This method returns a CustomProperties object in the callback, which provides methods to access the custom properties specific to the current item and the current add-in. Custom properties are not encrypted on the item, so this should not be used as secure storage.

The custom properties are provided as a CustomProperties object in the asyncResult.value property. This object can be used to get, set, and remove custom properties from the item and save changes to the custom property set back to the server.

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 Item 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 Item object model events section.

Property Details

attachments

Gets the item's attachments as an array.

attachments: AttachmentDetails[];

Property Value

Remarks

Minimum permission level: ReadItem

Applicable Outlook mode: Appointment Attendee

Note: Certain types of files are blocked by Outlook due to potential security issues and are therefore not returned. For more information, see Blocked attachments in Outlook.

Examples

// The following code builds an HTML string with details of all attachments on the current item.
const item = Office.context.mailbox.item;
let outputString = "";

if (item.attachments.length > 0) {
    for (let i = 0 ; i < item.attachments.length ; i++) {
        const attachment = item.attachments[i];
        outputString += "<BR>" + i + ". Name: ";
        outputString += attachment.name;
        outputString += "<BR>ID: " + attachment.id;
        outputString += "<BR>contentType: " + attachment.contentType;
        outputString += "<BR>size: " + attachment.size;
        outputString += "<BR>attachmentType: " + attachment.attachmentType;
        outputString += "<BR>isInline: " + attachment.isInline;
    }
}

console.log(outputString);
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/40-attachments/get-attachments-read.yaml
const attachments = Office.context.mailbox.item.attachments;
console.log(attachments);

body

Gets an object that provides methods for manipulating the body of an item.

body: Body;

Property Value

Remarks

[ API set: Mailbox 1.1 ]

Minimum permission level: ReadItem

Applicable Outlook mode: Appointment Attendee

Examples

// This example gets the body of the item as plain text.
Office.context.mailbox.item.body.getAsync(
    "text",
    { asyncContext: "This is passed to the callback" },
    function callback(result) {
        // Do something with the result.
    });

// The following is an example of the result parameter passed to the callback function.
{
    "value": "TEXT of whole body (including threads below)",
    "status": "succeeded",
    "asyncContext": "This is passed to the callback"
}

categories

Gets an object that provides methods for managing the item's categories.

categories: Categories;

Property Value

Remarks

[ API set: Mailbox 1.8 ]

Minimum permission level: ReadItem

Applicable Outlook mode: Appointment Attendee

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/45-categories/work-with-categories.yaml
Office.context.mailbox.item.categories.getAsync(function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    const categories = asyncResult.value;
    if (categories && categories.length > 0) {
      console.log("Categories assigned to this item:");
      console.log(JSON.stringify(categories));
    } else {
      console.log("There are no categories assigned to this item.");
    }
  } else {
    console.error(asyncResult.error);
  }
});
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/45-categories/work-with-categories.yaml
// Note: In order for you to successfully add a category,
// it must be in the mailbox categories master list.

Office.context.mailbox.masterCategories.getAsync(function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    const masterCategories = asyncResult.value;
    if (masterCategories && masterCategories.length > 0) {
      // Grab the first category from the master list.
      const categoryToAdd = [masterCategories[0].displayName];
      Office.context.mailbox.item.categories.addAsync(categoryToAdd, function(asyncResult) {
        if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
          console.log(`Successfully assigned category '${categoryToAdd}' to item.`);
        } else {
          console.log("categories.addAsync call failed with error: " + asyncResult.error.message);
        }
      });
    } else {
      console.log("There are no categories in the master list on this mailbox. You can add categories using Office.context.mailbox.masterCategories.addAsync.");
    }
  } else {
    console.error(asyncResult.error);
  }
});
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/45-categories/work-with-categories.yaml
Office.context.mailbox.item.categories.getAsync(function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    const categories = asyncResult.value;
    if (categories && categories.length > 0) {
      // Grab the first category assigned to this item.
      const categoryToRemove = [categories[0].displayName];
      Office.context.mailbox.item.categories.removeAsync(categoryToRemove, function(asyncResult) {
        if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
          console.log(`Successfully unassigned category '${categoryToRemove}' from this item.`);
        } else {
          console.log("categories.removeAsync call failed with error: " + asyncResult.error.message);
        }
      });
    } else {
      console.log("There are no categories assigned to this item.");
    }
  } else {
    console.error(asyncResult.error);
  }
});

dateTimeCreated

Gets the date and time that an item was created.

dateTimeCreated: Date;

Property Value

Date

Remarks

Minimum permission level: ReadItem

Applicable Outlook mode: Appointment Attendee

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/90-other-item-apis/get-date-time-created-read.yaml
console.log(`Creation date and time: ${Office.context.mailbox.item.dateTimeCreated}`);

dateTimeModified

Gets the date and time that an item was last modified.

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

dateTimeModified: Date;

Property Value

Date

Remarks

Minimum permission level: ReadItem

Applicable Outlook mode: Appointment Attendee

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/90-other-item-apis/get-date-time-modified-read.yaml
console.log(`Date and time item last modified: ${Office.context.mailbox.item.dateTimeModified}`);

end

Gets the date and time that the appointment is to end.

The end property is a Date object expressed as a Coordinated Universal Time (UTC) date and time value. You can use the convertToLocalClientTime method to convert the end property value to the client's local date and time.

When you use the Time.setAsync method to set the end time, you should use the convertToUtcClientTime method to convert the local time on the client to UTC for the server.

end: Date;

Property Value

Date

Remarks

Minimum permission level: ReadItem

Applicable Outlook mode: Appointment Attendee

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/90-other-item-apis/get-end-read.yaml
console.log(`Appointment ends: ${Office.context.mailbox.item.end}`);

enhancedLocation

Gets the locations of an appointment.

The enhancedLocation property returns an EnhancedLocation object that allows you to get the set of locations (each represented by a LocationDetails object) associated with the appointment.

enhancedLocation: EnhancedLocation;

Property Value

Remarks

[ API set: Mailbox 1.8 ]

Minimum permission level: ReadItem

Applicable Outlook mode: Appointment Attendee

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/90-other-item-apis/get-add-remove-enhancedlocation-appointment.yaml
Office.context.mailbox.item.enhancedLocation.getAsync((result) => {
  if (result.status !== Office.AsyncResultStatus.Succeeded) {
    console.error(`Failed to get locations. Error message: ${result.error.message}`);
    return;
  }
  const places = result.value;
  if (places && places.length > 0) {
    result.value.forEach(function(place) {
      console.log(`Location: ${place.displayName} (type: ${place.locationIdentifier.type})`);
      if (place.locationIdentifier.type === Office.MailboxEnums.LocationType.Room) {
        console.log("Email address: " + place.emailAddress);
      }
    });
  } else {
    console.log("There are no locations.");
  }
});

isAllDayEvent

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Returns a boolean value indicating whether the event is all day.

isAllDayEvent: boolean;

Property Value

boolean

Remarks

[ API set: Mailbox preview ]

Minimum permission level: ReadItem

Applicable Outlook mode: Appointment Attendee

Examples

const isAllDayEvent = Office.context.mailbox.item.isAllDayEvent;
console.log("Is this an all-day event? " + isAllDayEvent);

itemClass

Gets the Exchange Web Services item class of the selected item.

You can create custom message classes that extends a default message class, for example, a custom appointment message class IPM.Appointment.Contoso.

itemClass: string;

Property Value

string

Remarks

Minimum permission level: ReadItem

Applicable Outlook mode: Appointment Attendee

The itemClass property specifies the message class of the selected item. The following are the default message classes for the message or appointment item.

Type Description Item Class
Appointment items These are calendar items of the item class IPM.Appointment or IPM.Appointment.Occurrence. IPM.Appointment,IPM.Appointment.Occurrence
Message items These include email messages that have the default message class IPM.Note, and meeting requests, responses, and cancellations, that use IPM.Schedule.Meeting as the base message class. IPM.Note,IPM.Schedule.Meeting.Request,IPM.Schedule.Meeting.Neg,IPM.Schedule.Meeting.Pos,IPM.Schedule.Meeting.Tent,IPM.Schedule.Meeting.Canceled

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/90-other-item-apis/get-item-class-read.yaml
console.log(`Item class: ${Office.context.mailbox.item.itemClass}`);

itemId

Gets the Exchange Web Services item identifier for the current item.

The itemId property is not available in compose mode. If an item identifier is required, the saveAsync method can be used to save the item to the store, which will return the item identifier in the asyncResult.value parameter in the callback function.

Note: The identifier returned by the itemId property is the same as the Exchange Web Services item identifier. The itemId property is not identical to the Outlook Entry ID or the ID used by the Outlook REST API. Before making REST API calls using this value, it should be converted using Office.context.mailbox.convertToRestId. For more details, see Use the Outlook REST APIs from an Outlook add-in.

itemId: string;

Property Value

string

Remarks

Minimum permission level: ReadItem

Applicable Outlook mode: Appointment Attendee

Examples

// The following code checks for the presence of an item
// identifier. If the `itemId` property returns `null` or
// `undefined`, it saves the item to the store and gets the
// item identifier from the asynchronous result.
// **Important**: `saveAsync` was introduced with requirement set 1.3
// so you can't get the `itemId` in Compose mode in earlier sets.
let itemId = Office.context.mailbox.item.itemId;
if (itemId === null || itemId == undefined) {
    Office.context.mailbox.item.saveAsync(function(result) {
        itemId = result.value;
    });
}

itemType

Gets the type of item that an instance represents.

The itemType property returns one of the ItemType enumeration values, indicating whether the item object instance is a message or an appointment.

itemType: MailboxEnums.ItemType | string;

Property Value

Remarks

Minimum permission level: ReadItem

Applicable Outlook mode: Appointment Attendee

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/90-other-item-apis/get-item-type.yaml
const itemType = Office.context.mailbox.item.itemType;
switch (itemType) {
    case Office.MailboxEnums.ItemType.Appointment:
        console.log(`Current item is an ${itemType}.`);
        break;
    case Office.MailboxEnums.ItemType.Message:
        console.log(`Current item is a ${itemType}. A message could be an email, meeting request, meeting response, or meeting cancellation.`);
        break;
}

location

Gets the location of an appointment.

The location property returns a string that contains the location of the appointment.

location: string;

Property Value

string

Remarks

Minimum permission level: ReadItem

Applicable Outlook mode: Appointment Attendee

Examples

const location = Office.context.mailbox.item.location;
console.log("location: " + location);
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/90-other-item-apis/get-location-read.yaml
console.log(`Appointment location: ${Office.context.mailbox.item.location}`);

normalizedSubject

Gets the subject of an item, with all prefixes removed (including RE: and FWD:).

The normalizedSubject property gets the subject of the item, with any standard prefixes (such as RE: and FW:) that are added by email programs. To get the subject of the item with the prefixes intact, use the subject property.

normalizedSubject: string;

Property Value

string

Remarks

Minimum permission level: ReadItem

Applicable Outlook mode: Appointment Attendee

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/90-other-item-apis/get-normalized-subject-read.yaml
console.log(`Normalized subject: ${Office.context.mailbox.item.normalizedSubject}`);

notificationMessages

Gets the notification messages for an item.

notificationMessages: NotificationMessages;

Property Value

Remarks

[ API set: Mailbox 1.3 ]

Minimum permission level: ReadItem

Applicable Outlook mode: Appointment Attendee

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/35-notifications/add-getall-remove.yaml
const id = $("#notificationId").val();
const details =
  {
    type: Office.MailboxEnums.ItemNotificationMessageType.ProgressIndicator,
    message: "Progress indicator with id = " + id
  };
Office.context.mailbox.item.notificationMessages.addAsync(id, details, handleResult);
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/35-notifications/add-getall-remove.yaml
const id = $("#notificationId").val();
const details =
  {
    type: Office.MailboxEnums.ItemNotificationMessageType.InformationalMessage,
    message: "Non-persistent informational notification message with id = " + id,
    icon: "icon1",
    persistent: false
  };
Office.context.mailbox.item.notificationMessages.addAsync(id, details, handleResult);
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/35-notifications/add-getall-remove.yaml
const id = $("#notificationId").val();
const details =
  {
    type: Office.MailboxEnums.ItemNotificationMessageType.InformationalMessage,
    message: "Persistent informational notification message with id = " + id,
    icon: "icon1",
    persistent: true
  };
Office.context.mailbox.item.notificationMessages.addAsync(id, details, handleResult);
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/35-notifications/add-getall-remove.yaml
Office.context.mailbox.item.notificationMessages.getAllAsync(handleResult);          
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/35-notifications/add-getall-remove.yaml
const id = $("#notificationId").val();
Office.context.mailbox.item.notificationMessages.replaceAsync(
  id,
  {
    type: Office.MailboxEnums.ItemNotificationMessageType.InformationalMessage,
    message: "Notification message with id = " + id + " has been replaced with an informational message.",
    icon: "icon2",
    persistent: false
  },
  handleResult);
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/35-notifications/add-getall-remove.yaml
const id = $("#notificationId").val();
Office.context.mailbox.item.notificationMessages.removeAsync(id, handleResult);

optionalAttendees

Provides access to the optional attendees of an event. The type of object and level of access depend on the mode of the current item.

The optionalAttendees property returns an array that contains an EmailAddressDetails object for each optional attendee to the meeting. Collection size limits:

  • Windows: 500 members

  • Classic Mac UI: 100 members

  • New Mac UI, web browser, Android: No limit

optionalAttendees: EmailAddressDetails[];

Property Value

Remarks

Minimum permission level: ReadItem

Applicable Outlook mode: Appointment Attendee

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/30-recipients-and-attendees/get-optional-attendees-appointment-attendee.yaml
const apptOptionalAttendees = Office.context.mailbox.item.optionalAttendees;
console.log("Optional attendees:");
for (let i = 0; i < apptOptionalAttendees.length; i++) {
  console.log(
    apptOptionalAttendees[i].displayName +
      " (" +
      apptOptionalAttendees[i].emailAddress +
      ") - response: " +
      apptOptionalAttendees[i].appointmentResponse
  );
}

organizer

Gets the meeting organizer's email properties.

organizer: EmailAddressDetails;

Property Value

Remarks

Minimum permission level: ReadItem

Applicable Outlook mode: Appointment Attendee

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/30-recipients-and-attendees/get-organizer-appointment-attendee.yaml
const apptOrganizer = Office.context.mailbox.item.organizer;
console.log("Organizer: " + apptOrganizer.displayName + " (" + apptOrganizer.emailAddress + ")");

recurrence

Gets the recurrence pattern of an appointment. Gets the recurrence pattern of a meeting request.

The recurrence property returns a Recurrence object for recurring appointments or meetings requests if an item is a series or an instance in a series. null is returned for single appointments and meeting requests of single appointments.

Note: Meeting requests have an itemClass value of IPM.Schedule.Meeting.Request.

Note: If the recurrence object is null, this indicates that the object is a single appointment or a meeting request of a single appointment and NOT a part of a series.

recurrence: Recurrence;

Property Value

Remarks

[ API set: Mailbox 1.7 ]

Minimum permission level: ReadItem

Applicable Outlook mode: Appointment Attendee

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/50-recurrence/get-recurrence-read.yaml
const recurrence = Office.context.mailbox.item.recurrence;

if (recurrence === undefined) {
  console.log("This item is a message but not a meeting request.");
} else if (recurrence === null) {
  console.log("This is a single appointment.");
} else {
  console.log(JSON.stringify(recurrence));
}

requiredAttendees

Provides access to the required attendees of an event. The type of object and level of access depend on the mode of the current item.

The requiredAttendees property returns an array that contains an EmailAddressDetails object for each required attendee to the meeting. Collection size limits:

  • Windows: 500 members

  • Classic Mac UI: 100 members

  • New Mac UI, web browser, Android: No limit

requiredAttendees: EmailAddressDetails[];

Property Value

Remarks

Minimum permission level: ReadItem

Applicable Outlook mode: Appointment Attendee

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/30-recipients-and-attendees/get-required-attendees-appointment-attendee.yaml
const apptRequiredAttendees = Office.context.mailbox.item.requiredAttendees;
console.log("Required attendees:");
for (let i = 0; i < apptRequiredAttendees.length; i++) {
  console.log(
    apptRequiredAttendees[i].displayName +
      " (" +
      apptRequiredAttendees[i].emailAddress +
      ") - response: " +
      apptRequiredAttendees[i].appointmentResponse
  );
}

sensitivity

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Provides the sensitivity value of the appointment.

sensitivity: MailboxEnums.AppointmentSensitivityType;

Property Value

Remarks

[ API set: Mailbox preview ]

Minimum permission level: ReadItem

Applicable Outlook mode: Appointment Attendee

Examples

const sensitivity = Office.context.mailbox.item.sensitivity;
console.log("Sensitivity: " + sensitivity);

seriesId

Gets the ID of the series that an instance belongs to.

In Outlook on the web and desktop clients, the seriesId returns the Exchange Web Services (EWS) ID of the parent (series) item that this item belongs to. However, on iOS and Android, the seriesId returns the REST ID of the parent item.

Note: The identifier returned by the seriesId property is the same as the Exchange Web Services item identifier. The seriesId property is not identical to the Outlook IDs used by the Outlook REST API. Before making REST API calls using this value, it should be converted using Office.context.mailbox.convertToRestId. For more details, see Use the Outlook REST APIs from an Outlook add-in.

The seriesId property returns null for items that do not have parent items such as single appointments, series items, or meeting requests and returns undefined for any other items that are not meeting requests.

seriesId: string;

Property Value

string

Remarks

[ API set: Mailbox 1.7 ]

Minimum permission level: ReadItem

Applicable Outlook mode: Appointment Attendee

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/50-recurrence/get-series-id.yaml
const seriesId = Office.context.mailbox.item.seriesId;

if (seriesId === undefined) {
  console.log("This is a message that's not a meeting request.");
} else if (seriesId === null) {
  console.log("This is a single appointment, a parent series, or a meeting request for a series or single meeting.");
} else {
  console.log("This is an instance belonging to series with ID " + seriesId);
}

start

Gets the date and time that the appointment is to begin.

The start property is a Date object expressed as a Coordinated Universal Time (UTC) date and time value. You can use the convertToLocalClientTime method to convert the value to the client's local date and time.

start: Date;

Property Value

Date

Remarks

Minimum permission level: ReadItem

Applicable Outlook mode: Appointment Attendee

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/90-other-item-apis/get-start-read.yaml
console.log(`Appointment starts: ${Office.context.mailbox.item.start}`);

subject

Gets the description that appears in the subject field of an item.

The subject property gets or sets the entire subject of the item, as sent by the email server.

The subject property returns a string. Use the normalizedSubject property to get the subject minus any leading prefixes such as RE: and FW:.

subject: string;

Property Value

string

Remarks

Minimum permission level: ReadItem

Applicable Outlook mode: Appointment Attendee

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/90-other-item-apis/get-subject-read.yaml
console.log(`Subject: ${Office.context.mailbox.item.subject}`);

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

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

callback

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

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

Returns

void

Remarks

[ API set: Mailbox 1.7 ]

Minimum permission level: ReadItem

Applicable Outlook mode: Appointment Attendee

Examples

function myHandlerFunction(eventarg) {
    if (eventarg.attachmentStatus === Office.MailboxEnums.AttachmentStatus.Added) {
        const attachment = eventarg.attachmentDetails;
        console.log("Event Fired and Attachment Added!");
        getAttachmentContentAsync(attachment.id, options, callback);
    }
}

Office.context.mailbox.item.addHandlerAsync(Office.EventType.AttachmentsChanged, myHandlerFunction, myCallback);

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 Item 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, asyncResult, which is an Office.AsyncResult object.

Returns

void

Remarks

[ API set: Mailbox 1.7 ]

Minimum permission level: ReadItem

Applicable Outlook mode: Appointment Attendee

displayReplyAllForm(formData)

Displays a reply form that includes either the sender and all recipients of the selected message or the organizer and all attendees of the selected appointment.

In Outlook on the web, the reply form is displayed as a pop-out form in the 3-column view and a pop-up form in the 2-column or 1-column view.

If any of the string parameters exceed their limits, displayReplyAllForm throws an exception.

When attachments are specified in the formData.attachments parameter, Outlook attempts to download all attachments and attach them to the reply form. If any attachments fail to be added, an error is shown in the form UI. If this isn't possible, then no error message is thrown.

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

displayReplyAllForm(formData: string | ReplyFormData): void;

Parameters

formData

string | Office.ReplyFormData

A string that contains text and HTML and that represents the body of the reply form. The string is limited to 32 KB OR a ReplyFormData object that contains body or attachment data and a callback function.

Returns

void

Remarks

Minimum permission level: ReadItem

Applicable Outlook mode: Appointment Attendee

Examples

// The following code passes a string to the `displayReplyAllForm` method.
Office.context.mailbox.item.displayReplyAllForm('hello there');
Office.context.mailbox.item.displayReplyAllForm('<b>hello there</b>');

// Reply with an empty body.
Office.context.mailbox.item.displayReplyAllForm({});

// Reply with just a body.
Office.context.mailbox.item.displayReplyAllForm(
{
'htmlBody' : 'hi'
});

// Reply with a body and a file attachment.
Office.context.mailbox.item.displayReplyAllForm(
{
    'htmlBody' : 'hi',
    'attachments' :
    [
        {
        'type' : Office.MailboxEnums.AttachmentType.File,
        'name' : 'squirrel.png',
        'url' : 'http://i.imgur.com/sRgTlGR.jpg'
        }
    ]
});

// Reply with a body and an item attachment.
Office.context.mailbox.item.displayReplyAllForm(
{
    'htmlBody' : 'hi',
    'attachments' :
    [
        {
        'type' : 'item',
        'name' : 'rand',
        'itemId' : Office.context.mailbox.item.itemId
        }
    ]
});

// Reply with a body, file attachment, item attachment, and a callback.
Office.context.mailbox.item.displayReplyAllForm(
{
    'htmlBody' : 'hi',
    'attachments' :
    [
        {
            'type' : Office.MailboxEnums.AttachmentType.File,
            'name' : 'squirrel.png',
            'url' : 'http://i.imgur.com/sRgTlGR.jpg'
        },
        {
            'type' : 'item',
            'name' : 'rand',
            'itemId' : Office.context.mailbox.item.itemId
        }
    ],
    'callback' : function(asyncResult)
    {
        console.log(asyncResult.value);
    }
});
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/55-display-items/display-reply-forms.yaml
Office.context.mailbox.item.displayReplyAllForm("This is a reply ALL with <b>some bold text</b>.");

displayReplyAllFormAsync(formData, options, callback)

Displays a reply form that includes either the sender and all recipients of the selected message or the organizer and all attendees of the selected appointment.

In Outlook on the web, the reply form is displayed as a pop-out form in the 3-column view and a pop-up form in the 2-column or 1-column view.

If any of the string parameters exceed their limits, displayReplyAllFormAsync throws an exception.

When attachments are specified in the formData.attachments parameter, Outlook attempts to download all attachments and attach them to the reply form. If any attachments fail to be added, an error is shown in the form UI. If this isn't possible, then no error message is thrown.

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

displayReplyAllFormAsync(formData: string | ReplyFormData, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameters

formData

string | Office.ReplyFormData

A string that contains text and HTML and that represents the body of the reply form. The string is limited to 32 KB OR a ReplyFormData object that contains body or attachment data and a callback function.

options
Office.AsyncContextOptions

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

callback

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

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

Returns

void

Remarks

[ API set: Mailbox 1.9 ]

Minimum permission level: ReadItem

Applicable Outlook mode: Appointment Attendee

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/55-display-items/display-reply-forms.yaml
Office.context.mailbox.item.displayReplyAllFormAsync("This is a reply ALL with <b>some bold text</b>.", function(
  asyncResult
) {
  console.log(JSON.stringify(asyncResult));
});

displayReplyAllFormAsync(formData, callback)

Displays a reply form that includes either the sender and all recipients of the selected message or the organizer and all attendees of the selected appointment.

In Outlook on the web, the reply form is displayed as a pop-out form in the 3-column view and a pop-up form in the 2-column or 1-column view.

If any of the string parameters exceed their limits, displayReplyAllFormAsync throws an exception.

When attachments are specified in the formData.attachments parameter, Outlook attempts to download all attachments and attach them to the reply form. If any attachments fail to be added, an error is shown in the form UI. If this isn't possible, then no error message is thrown.

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

displayReplyAllFormAsync(formData: string | ReplyFormData, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameters

formData

string | Office.ReplyFormData

A string that contains text and HTML and that represents the body of the reply form. The string is limited to 32 KB OR a ReplyFormData object that contains body or attachment data and a callback function.

callback

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

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

Returns

void

Remarks

[ API set: Mailbox 1.9 ]

Minimum permission level: ReadItem

Applicable Outlook mode: Appointment Attendee

displayReplyForm(formData)

Displays a reply form that includes only the sender of the selected message or the organizer of the selected appointment.

In Outlook on the web, the reply form is displayed as a pop-out form in the 3-column view and a pop-up form in the 2-column or 1-column view.

If any of the string parameters exceed their limits, displayReplyForm throws an exception.

When attachments are specified in the formData.attachments parameter, Outlook attempts to download all attachments and attach them to the reply form. If any attachments fail to be added, an error is shown in the form UI. If this isn't possible, then no error message is thrown.

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

displayReplyForm(formData: string | ReplyFormData): void;

Parameters

formData

string | Office.ReplyFormData

A string that contains text and HTML and that represents the body of the reply form. The string is limited to 32 KB OR a ReplyFormData object that contains body or attachment data and a callback function.

Returns

void

Remarks

Minimum permission level: ReadItem

Applicable Outlook mode: Appointment Attendee

Examples

// The following code passes a string to the `displayReplyForm` method.
Office.context.mailbox.item.displayReplyForm('hello there');
Office.context.mailbox.item.displayReplyForm('<b>hello there</b>');

// Reply with an empty body.
Office.context.mailbox.item.displayReplyForm({});

// Reply with just a body.
Office.context.mailbox.item.displayReplyForm(
{
    'htmlBody' : 'hi'
});

// Reply with a body and a file attachment.
Office.context.mailbox.item.displayReplyForm(
{
    'htmlBody' : 'hi',
    'attachments' :
    [
        {
            'type' : Office.MailboxEnums.AttachmentType.File,
            'name' : 'squirrel.png',
            'url' : 'http://i.imgur.com/sRgTlGR.jpg'
        }
    ]
});

// Reply with a body and an item attachment.
Office.context.mailbox.item.displayReplyForm(
{
    'htmlBody' : 'hi',
    'attachments' :
    [
        {
            'type' : 'item',
            'name' : 'rand',
            'itemId' : Office.context.mailbox.item.itemId
        }
    ]
});

// Reply with a body, file attachment, item attachment, and a callback.
Office.context.mailbox.item.displayReplyForm(
{
    'htmlBody' : 'hi',
    'attachments' :
    [
        {
            'type' : Office.MailboxEnums.AttachmentType.File,
            'name' : 'squirrel.png',
            'url' : 'http://i.imgur.com/sRgTlGR.jpg'
        },
        {
            'type' : 'item',
            'name' : 'rand',
            'itemId' : Office.context.mailbox.item.itemId
        }
    ],
    'callback' : function(asyncResult)
    {
        console.log(asyncResult.value);
    }
});
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/55-display-items/display-reply-forms.yaml
Office.context.mailbox.item.displayReplyForm("This is a reply with <i>some text in italics</i>.");
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/55-display-items/display-reply-with-attachments.yaml
Office.context.mailbox.item.displayReplyForm({
  htmlBody: "This is a reply with a couple of attachments - an inline image and an item<br><img src='cid:dog.jpg'>",
  attachments: [
    { type: "file", url: "http://i.imgur.com/9S36xvA.jpg", name: "dog.jpg", isInline: true },
    { type: "item", itemId: Office.context.mailbox.item.itemId, name: "test_email.msg" }
  ],
  options: { asyncContext: null },
  callback: function(result) {
    if (result.status !== Office.AsyncResultStatus.Succeeded) {
      console.error(`Action failed with message ${result.error.message}`);
    }
  }
});

displayReplyFormAsync(formData, options, callback)

Displays a reply form that includes only the sender of the selected message or the organizer of the selected appointment.

In Outlook on the web, the reply form is displayed as a pop-out form in the 3-column view and a pop-up form in the 2-column or 1-column view.

If any of the string parameters exceed their limits, displayReplyFormAsync throws an exception.

When attachments are specified in the formData.attachments parameter, Outlook attempts to download all attachments and attach them to the reply form. If any attachments fail to be added, an error is shown in the form UI. If this isn't possible, then no error message is thrown.

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

displayReplyFormAsync(formData: string | ReplyFormData, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameters

formData

string | Office.ReplyFormData

A string that contains text and HTML and that represents the body of the reply form. The string is limited to 32 KB OR a ReplyFormData object that contains body or attachment data and a callback function.

options
Office.AsyncContextOptions

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

callback

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

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

Returns

void

Remarks

[ API set: Mailbox 1.9 ]

Minimum permission level: ReadItem

Applicable Outlook mode: Appointment Attendee

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/55-display-items/display-reply-forms.yaml
Office.context.mailbox.item.displayReplyFormAsync("This is a reply with <i>some text in italics</i>.", function(
  asyncResult
) {
  console.log(JSON.stringify(asyncResult));
});
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/55-display-items/display-reply-with-attachments.yaml
// 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.item.displayReplyFormAsync(
  {
    htmlBody: "This is a reply with a couple of attachments - an inline image and an item<br><img src='cid:dog.jpg'>",
    attachments: [
      { type: "file", url: "http://i.imgur.com/9S36xvA.jpg", name: "dog.jpg", isInline: true },
      { type: "item", itemId: Office.context.mailbox.item.itemId, name: "test_email.msg" }
    ]
  },
  function(asyncResult) {
    console.log(JSON.stringify(asyncResult));
  }
);

displayReplyFormAsync(formData, callback)

Displays a reply form that includes only the sender of the selected message or the organizer of the selected appointment.

In Outlook on the web, the reply form is displayed as a pop-out form in the 3-column view and a pop-up form in the 2-column or 1-column view.

If any of the string parameters exceed their limits, displayReplyFormAsync throws an exception.

When attachments are specified in the formData.attachments parameter, Outlook attempts to download all attachments and attach them to the reply form. If any attachments fail to be added, an error is shown in the form UI. If this isn't possible, then no error message is thrown.

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

displayReplyFormAsync(formData: string | ReplyFormData, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameters

formData

string | Office.ReplyFormData

A string that contains text and HTML and that represents the body of the reply form. The string is limited to 32 KB OR a ReplyFormData object that contains body or attachment data and a callback function.

callback

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

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

Returns

void

Remarks

[ API set: Mailbox 1.9 ]

Minimum permission level: ReadItem

Applicable Outlook mode: Appointment Attendee

getAttachmentContentAsync(attachmentId, options, callback)

Gets an attachment from a message or appointment and returns it as an AttachmentContent object.

The getAttachmentContentAsync method gets the attachment with the specified identifier from the item. As a best practice, you should get the attachment's identifier from an item.attachments call, then in the same session, use that identifier to retrieve the attachment. In Outlook on the web and mobile devices, the attachment identifier is valid only within the same session. A session is over when the user closes the app, or if the user starts composing an inline form then subsequently pops out the form to continue in a separate window.

getAttachmentContentAsync(attachmentId: string, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<AttachmentContent>) => void): void;

Parameters

attachmentId

string

The identifier of the attachment you want to get.

options
Office.AsyncContextOptions

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

callback

(asyncResult: Office.AsyncResult<Office.AttachmentContent>) => 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. If the call fails, the asyncResult.error property will contain an error code with the reason for the failure.

Returns

void

Remarks

[ API set: Mailbox 1.8 ]

Minimum permission level: ReadItem

Applicable Outlook mode: Appointment Attendee

Errors:

  • AttachmentTypeNotSupported: The attachment type isn't supported. Unsupported types include embedded images in Rich Text Format, or item attachment types other than email or calendar items (such as a contact or task item).

  • InvalidAttachmentId: The attachment identifier does not exist.

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/40-attachments/get-attachment-content.yaml
// Gets the attachments of the current message or appointment in read mode.
// The item.attachments call can only be used in read mode.
const attachments = item.attachments;
if (attachments.length <= 0) {
  console.log("Mail item has no attachments.");
  return;
}

for (let i = 0; i < attachments.length; i++) {
  // Log the attachment type and its contents to the console.
  item.getAttachmentContentAsync(attachments[i].id, handleAttachmentsCallback);
}

getAttachmentContentAsync(attachmentId, callback)

Gets an attachment from a message or appointment and returns it as an AttachmentContent object.

The getAttachmentContentAsync method gets the attachment with the specified identifier from the item. As a best practice, you should get the attachment's identifier from an item.attachments call, then in the same session, use that identifier to retrieve the attachment. In Outlook on the web and mobile devices, the attachment identifier is valid only within the same session. A session is over when the user closes the app, or if the user starts composing an inline form then subsequently pops out the form to continue in a separate window.

getAttachmentContentAsync(attachmentId: string, callback?: (asyncResult: Office.AsyncResult<AttachmentContent>) => void): void;

Parameters

attachmentId

string

The identifier of the attachment you want to get.

callback

(asyncResult: Office.AsyncResult<Office.AttachmentContent>) => 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. If the call fails, the asyncResult.error property will contain an error code with the reason for the failure.

Returns

void

Remarks

[ API set: Mailbox 1.8 ]

Minimum permission level: ReadItem

Applicable Outlook mode: Appointment Attendee

Errors:

  • AttachmentTypeNotSupported: The attachment type isn't supported. Unsupported types include embedded images in Rich Text Format, or item attachment types other than email or calendar items (such as a contact or task item).

  • InvalidAttachmentId: The attachment identifier does not exist.

getEntities()

Gets the entities found in the selected item's body.

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

getEntities(): Entities;

Returns

Remarks

Minimum permission level: ReadItem

Applicable Outlook mode: Appointment Attendee

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/75-entities-and-regex-matches/basic-entities.yaml
const entities = Office.context.mailbox.item.getEntities();
let entityTypesFound = 0;
if (entities.addresses.length > 0) {
    console.warn("physical addresses: ");
    console.log(entities.addresses);
    entityTypesFound++;
}
if (entities.contacts.length > 0) {
    console.warn("contacts: ");
    entities.contacts.forEach(function (contact) { console.log(contact.personName); })
    entityTypesFound++;
}
if (entities.emailAddresses.length > 0) {
    console.warn("email addresses: ");
    console.log(entities.emailAddresses);
    entityTypesFound++;
}
if (entities.meetingSuggestions.length > 0) {
    console.warn("meetings suggestions: ");
    entities.meetingSuggestions.forEach(function (meetingSuggestion) { console.log(meetingSuggestion.meetingString); })
    entityTypesFound++;
}
if (entities.phoneNumbers.length > 0) {
    console.warn("phone numbers: ");
    entities.phoneNumbers.forEach(function (phoneNumber) { console.log(phoneNumber.originalPhoneString); })
    entityTypesFound++;
}
if (entities.taskSuggestions.length > 0) {
    console.warn("task suggestions: ");
    entities.taskSuggestions.forEach(function (taskSuggestion) { console.log(taskSuggestion.taskString); })
    entityTypesFound++;
}
if (entities.urls.length > 0) {
    console.warn("URLs: ");
    console.log(entities.urls);
    entityTypesFound++;
}
if (entityTypesFound == 0)
{
    console.log("No entities found on this item.");
}

getEntitiesByType(entityType)

Gets an array of all the entities of the specified entity type found in the selected item's body.

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

getEntitiesByType(entityType: MailboxEnums.EntityType | string): (string | Contact | MeetingSuggestion | PhoneNumber | TaskSuggestion)[];

Parameters

entityType

Office.MailboxEnums.EntityType | string

One of the EntityType enumeration values.

While the minimum permission level to use this method is Restricted, some entity types require ReadItem to access, as specified in the following table.

Value of entityType Type of objects in returned array Required Permission Level
Address String Restricted
Contact Contact ReadItem
EmailAddress String ReadItem
MeetingSuggestion MeetingSuggestion ReadItem
PhoneNumber PhoneNumber Restricted
TaskSuggestion TaskSuggestion ReadItem
URL String Restricted

Returns

If the value passed in entityType is not a valid member of the EntityType enumeration, the method returns null. If no entities of the specified type are present in the item's body, the method returns an empty array. Otherwise, the type of the objects in the returned array depends on the type of entity requested in the entityType parameter.

Remarks

Minimum permission level: Restricted

Applicable Outlook mode: Appointment Attendee

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/75-entities-and-regex-matches/basic-entities.yaml
console.log(Office.context.mailbox.item.getEntitiesByType(Office.MailboxEnums.EntityType.Address));

getFilteredEntitiesByName(name)

Returns well-known entities in the selected item that pass the named filter defined in the manifest XML file.

The getFilteredEntitiesByName method returns the entities that match the regular expression defined in the ItemHasKnownEntity rule element in the manifest XML file with the specified FilterName element value.

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

getFilteredEntitiesByName(name: string): (string | Contact | MeetingSuggestion | PhoneNumber | TaskSuggestion)[];

Parameters

name

string

The name of the ItemHasKnownEntity rule element that defines the filter to match.

Returns

If there is no ItemHasKnownEntity element in the manifest with a FilterName element value that matches the name parameter, the method returns null. If the name parameter matches an ItemHasKnownEntity element in the manifest, but there are no entities in the current item that match, the method return an empty array.

Remarks

Minimum permission level: ReadItem

Applicable Outlook mode: Appointment Attendee

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/75-entities-and-regex-matches/contextual.yaml
// This API would only work when you click on highlighted physical address that has the word "Way" in it.
console.log(Office.context.mailbox.item.getFilteredEntitiesByName("sampleFilterName"));

getInitializationContextAsync(options, callback)

Gets initialization data passed when the add-in is activated by an actionable message.

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

Parameters

options
Office.AsyncContextOptions

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

callback

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

Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type Office.AsyncResult. On success, the initialization context data is provided in the asyncResult.value property as a string. If there is no initialization context, the asyncResult object will contain an Error object with its code property set to 9020 and its name property set to GenericResponseError.

Returns

void

Remarks

[ API set: Mailbox 1.8 ]

Minimum permission level: ReadItem

Applicable Outlook mode: Appointment Attendee

Examples

// Get the initialization context (if present).
Office.context.mailbox.item.getInitializationContextAsync(
    function(asyncResult) {
        if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
            if (asyncResult.value != null && asyncResult.value.length > 0) {
                // The value is a string, parse to an object.
                const context = JSON.parse(asyncResult.value);
                // Do something with context.
            } else {
                // Empty context, treat as no context.
            }
        } else {
            if (asyncResult.error.code == 9020) {
                // GenericResponseError returned when there is no context.
                // Treat as no context.
            } else {
                // Handle the error.
            }
        }
    }
);

getInitializationContextAsync(callback)

Gets initialization data passed when the add-in is activated by an actionable message.

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

Parameters

callback

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

Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type Office.AsyncResult. On success, the initialization context data is provided in the asyncResult.value property as a string. If there is no initialization context, the asyncResult object will contain an Error object with its code property set to 9020 and its name property set to GenericResponseError.

Returns

void

Remarks

[ API set: Mailbox 1.8 ]

Minimum permission level: ReadItem

Applicable Outlook mode: Appointment Attendee

getRegExMatches()

Returns string values in the selected item that match the regular expressions defined in the manifest XML file.

The getRegExMatches method returns the strings that match the regular expression defined in each ItemHasRegularExpressionMatch or ItemHasKnownEntity rule element in the manifest XML file. For an ItemHasRegularExpressionMatch rule, a matching string has to occur in the property of the item that is specified by that rule. The PropertyName simple type defines the supported properties.

If you specify an ItemHasRegularExpressionMatch rule on the body property of an item, the regular expression should further filter the body and should not attempt to return the entire body of the item. Using a regular expression such as .* to obtain the entire body of an item does not always return the expected results. Instead, use the Body.getAsync method to retrieve the entire body.

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

getRegExMatches(): any;

Returns

any

An object that contains arrays of strings that match the regular expressions defined in the manifest XML file. The name of each array is equal to the corresponding value of the RegExName attribute of the matching ItemHasRegularExpressionMatch rule or the FilterName attribute of the matching ItemHasKnownEntity rule.

Remarks

Minimum permission level: ReadItem

Applicable Outlook mode: Appointment Attendee

Examples

// Consider an add-in manifest has the following `Rule` element:
//<Rule xsi:type="RuleCollection" Mode="And">
//  <Rule xsi:type="ItemIs" FormType="Read" ItemType="Message" />
//  <Rule xsi:type="RuleCollection" Mode="Or">
//    <Rule xsi:type="ItemHasRegularExpressionMatch" RegExName="fruits" RegExValue="apple|banana|coconut" PropertyName="BodyAsPlaintext" IgnoreCase="true" />
//    <Rule xsi:type="ItemHasRegularExpressionMatch" RegExName="veggies" RegExValue="tomato|onion|spinach|broccoli" PropertyName="BodyAsPlaintext" IgnoreCase="true" />
//  </Rule>
//</Rule>

// The object returned from `getRegExMatches` would have two properties: `fruits` and `veggies`.
//{
//'fruits': ['apple','banana','Banana','coconut'],
//'veggies': ['tomato','onion','spinach','broccoli']
//}

// The following example shows how to access the array of
// matches for the regular expression rule elements `fruits`
// and `veggies`, which are specified in the manifest.
const allMatches = Office.context.mailbox.item.getRegExMatches();
const fruits = allMatches.fruits;
const veggies = allMatches.veggies;
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/75-entities-and-regex-matches/contextual.yaml
// This API would only work when you click on highlighted word "ScriptLab".
console.log(Office.context.mailbox.item.getRegExMatches());

getRegExMatchesByName(name)

Returns string values in the selected item that match the named regular expression defined in the manifest XML file.

The getRegExMatchesByName method returns the strings that match the regular expression defined in the ItemHasRegularExpressionMatch rule element in the manifest XML file with the specified RegExName element value.

If you specify an ItemHasRegularExpressionMatch rule on the body property of an item, the regular expression should further filter the body and should not attempt to return the entire body of the item. Using a regular expression such as .* to obtain the entire body of an item does not always return the expected results.

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

getRegExMatchesByName(name: string): string[];

Parameters

name

string

The name of the ItemHasRegularExpressionMatch rule element that defines the filter to match.

Returns

string[]

An array that contains the strings that match the regular expression defined in the manifest XML file.

Remarks

Minimum permission level: ReadItem

Applicable Outlook mode: Appointment Attendee

Examples

// Consider an add-in manifest has the following `Rule` element:
//<Rule xsi:type="RuleCollection" Mode="And">
//  <Rule xsi:type="ItemIs" FormType="Read" ItemType="Message" />
//  <Rule xsi:type="RuleCollection" Mode="Or">
//    <Rule xsi:type="ItemHasRegularExpressionMatch" RegExName="fruits" RegExValue="apple|banana|coconut" PropertyName="BodyAsPlaintext" IgnoreCase="true" />
//    <Rule xsi:type="ItemHasRegularExpressionMatch" RegExName="veggies" RegExValue="tomato|onion|spinach|broccoli" PropertyName="BodyAsPlaintext" IgnoreCase="true" />
//  </Rule>
//</Rule>

// The object returned from `getRegExMatches` would have two properties: `fruits` and `veggies`.
//{
//'fruits': ['apple','banana','Banana','coconut'],
//'veggies': ['tomato','onion','spinach','broccoli']
//}

const fruits = Office.context.mailbox.item.getRegExMatchesByName("fruits");
const veggies = Office.context.mailbox.item.getRegExMatchesByName("veggies");
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/75-entities-and-regex-matches/contextual.yaml
// This API would only work when you click on highlighted word "ScriptLab".
console.log(Office.context.mailbox.item.getRegExMatchesByName("sampleRegexName"));

getSelectedEntities()

Gets the entities found in a highlighted match a user has selected. Highlighted matches apply to contextual add-ins.

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

getSelectedEntities(): Entities;

Returns

Remarks

[ API set: Mailbox 1.6 ]

Minimum permission level: ReadItem

Applicable Outlook mode: Appointment Attendee

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/75-entities-and-regex-matches/selected.yaml
const entities = Office.context.mailbox.item.getSelectedEntities();
let entityTypesFound = 0;
if (entities.addresses.length > 0) {
    console.warn("physical addresses: ");
    console.log(entities.addresses);
    entityTypesFound++;
}
if (entities.contacts.length > 0) {
    console.warn("contacts: ");
    entities.contacts.forEach(function (contact) { console.log(contact.personName); })
    entityTypesFound++;
}
if (entities.emailAddresses.length > 0) {
    console.warn("email addresses: ");
    console.log(entities.emailAddresses);
    entityTypesFound++;
}
if (entities.meetingSuggestions.length > 0) {
    console.warn("meetings suggestions: ");
    entities.meetingSuggestions.forEach(function (meetingSuggestion) { console.log(meetingSuggestion.meetingString); })
    entityTypesFound++;
}
if (entities.phoneNumbers.length > 0) {
    console.warn("phone numbers: ");
    entities.phoneNumbers.forEach(function (phoneNumber) { console.log(phoneNumber.originalPhoneString); })
    entityTypesFound++;
}
if (entities.taskSuggestions.length > 0) {
    console.warn("task suggestions: ");
    entities.taskSuggestions.forEach(function (taskSuggestion) { console.log(taskSuggestion.taskString); })
    entityTypesFound++;
}
if (entities.urls.length > 0) {
    console.warn("URLs: ");
    console.log(entities.urls);
    entityTypesFound++;
}
if (entityTypesFound == 0)
{
    console.error("Open add-in by clicking on a highlighted entity, for this API to return something useful.");
}

getSelectedRegExMatches()

Returns string values in a highlighted match that match the regular expressions defined in the manifest XML file. Highlighted matches apply to contextual add-ins.

The getSelectedRegExMatches method returns the strings that match the regular expression defined in each ItemHasRegularExpressionMatch or ItemHasKnownEntity rule element in the manifest XML file. For an ItemHasRegularExpressionMatch rule, a matching string has to occur in the property of the item that is specified by that rule. The PropertyName simple type defines the supported properties.

If you specify an ItemHasRegularExpressionMatch rule on the body property of an item, the regular expression should further filter the body and should not attempt to return the entire body of the item. Using a regular expression such as .* to obtain the entire body of an item does not always return the expected results. Instead, use the Body.getAsync method to retrieve the entire body

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

getSelectedRegExMatches(): any;

Returns

any

An object that contains arrays of strings that match the regular expressions defined in the manifest XML file. The name of each array is equal to the corresponding value of the RegExName attribute of the matching ItemHasRegularExpressionMatch rule or the FilterName attribute of the matching ItemHasKnownEntity rule.

Remarks

[ API set: Mailbox 1.6 ]

Minimum permission level: ReadItem

Applicable Outlook mode: Appointment Attendee

Examples

// Consider an add-in manifest has the following `Rule` element:
//<Rule xsi:type="RuleCollection" Mode="And">
//  <Rule xsi:type="ItemIs" FormType="Read" ItemType="Message" />
//  <Rule xsi:type="RuleCollection" Mode="Or">
//    <Rule xsi:type="ItemHasRegularExpressionMatch" RegExName="fruits" RegExValue="apple|banana|coconut" PropertyName="BodyAsPlaintext" IgnoreCase="true" />
//    <Rule xsi:type="ItemHasRegularExpressionMatch" RegExName="veggies" RegExValue="tomato|onion|spinach|broccoli" PropertyName="BodyAsPlaintext" IgnoreCase="true" />
//  </Rule>
//</Rule>

// The object returned from `getRegExMatches` would have two properties: `fruits` and `veggies`.
//{
//'fruits': ['apple','banana','Banana','coconut'],
//'veggies': ['tomato','onion','spinach','broccoli']
//}

// The following example shows how to access the array of matches for the
// regular expression rule elements `fruits` and `veggies`, which are
// specified in the manifest.
const selectedMatches = Office.context.mailbox.item.getSelectedRegExMatches();
const fruits = selectedMatches.fruits;
const veggies = selectedMatches.veggies;
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/75-entities-and-regex-matches/selected.yaml
const matches = Office.context.mailbox.item.getSelectedRegExMatches();
if (matches) {
    console.log(matches);
}
else {
    console.error("Open add-in by clicking on a highlighted regex match, for this API to return something useful.");
}

getSharedPropertiesAsync(options, callback)

Gets the properties of an appointment or message in a shared folder or shared mailbox (now in preview).

For more information around using this API, see the shared folders and shared mailbox article.

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

getSharedPropertiesAsync(options: Office.AsyncContextOptions, callback: (asyncResult: Office.AsyncResult<SharedProperties>) => void): void;

Parameters

options
Office.AsyncContextOptions

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

callback

(asyncResult: Office.AsyncResult<Office.SharedProperties>) => 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 properties of the shared item.

Returns

void

Remarks

[ API set: Mailbox 1.8 ]

Minimum permission level: ReadItem

Applicable Outlook mode: Appointment Attendee

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/65-delegates-and-shared-folders/get-shared-properties.yaml
if (!Office.context.mailbox.item.getSharedPropertiesAsync) {
  console.error("Try this sample on an appointment from a shared folder.");
  return;
}

Office.context.mailbox.getCallbackTokenAsync({ isRest: true }, function(result) {
  if (result.status === Office.AsyncResultStatus.Succeeded && result.value !== "") {
    Office.context.mailbox.item.getSharedPropertiesAsync(
      {
        // Pass auth token along.
        asyncContext: result.value
      },
      function(result2) {
        let sharedProperties = result2.value;
        let delegatePermissions = sharedProperties.delegatePermissions;

        // Determine if user has the appropriate permission to do the operation.
        if ((delegatePermissions & Office.MailboxEnums.DelegatePermissions.Read) != 0) {
          const ewsId = Office.context.mailbox.item.itemId;
          const restId = Office.context.mailbox.convertToRestId(ewsId, Office.MailboxEnums.RestVersion.v2_0);
          let rest_url =
            sharedProperties.targetRestUrl + "/v2.0/users/" + sharedProperties.targetMailbox + "/events/" + restId;

          $.ajax({
            url: rest_url,
            dataType: "json",
            headers: { Authorization: "Bearer " + result2.asyncContext }
          })
            .done(function(response) {
              console.log(response);
            })
            .fail(function(error) {
              console.error(error);
            });
        }
      }
    );
  }
});

getSharedPropertiesAsync(callback)

Gets the properties of an appointment or message in a shared folder or shared mailbox (now in preview).

For more information around using this API, see the shared folders and shared mailbox article.

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

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

Parameters

callback

(asyncResult: Office.AsyncResult<Office.SharedProperties>) => 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 properties of the shared item.

Returns

void

Remarks

[ API set: Mailbox 1.8 ]

Minimum permission level: ReadItem

Applicable Outlook mode: Appointment Attendee

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/65-delegates-and-shared-folders/get-shared-properties.yaml
if (!Office.context.mailbox.item.getSharedPropertiesAsync) {
  console.error("Try this sample on an item from a shared folder.");
  return;
}

Office.context.mailbox.item.getSharedPropertiesAsync(function(result) {
  console.log(result.value);
});

loadCustomPropertiesAsync(callback, userContext)

Asynchronously loads custom properties for this add-in on the selected item.

Custom properties are stored as key/value pairs on a per-app, per-item basis. This method returns a CustomProperties object in the callback, which provides methods to access the custom properties specific to the current item and the current add-in. Custom properties are not encrypted on the item, so this should not be used as secure storage.

The custom properties are provided as a CustomProperties object in the asyncResult.value property. This object can be used to get, set, and remove custom properties from the item and save changes to the custom property set back to the server.

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

Parameters

callback

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

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

userContext

any

Optional. Developers can provide any object they wish to access in the callback function. This object can be accessed by the asyncResult.asyncContext property in the callback function.

Returns

void

Remarks

Minimum permission level: ReadItem

Applicable Outlook mode: Appointment Attendee

Examples

// The following example shows how to use the loadCustomPropertiesAsync method
// to asynchronously load custom properties that are specific to the current item.
// The example also shows how to use the saveAsync method to save these properties
// back to the server. After loading the custom properties, the example uses the
// get method to read the custom property myProp, the set method to write the
// custom property otherProp, and then finally calls the saveAsync method to save
// the custom properties.
Office.initialize = function () {
    // Checks for the DOM to load using the jQuery ready method.
    $(document).ready(function () {
        // After the DOM is loaded, add-in-specific code can run.
        const mailbox = Office.context.mailbox;
        mailbox.item.loadCustomPropertiesAsync(customPropsCallback);
    });
};

function customPropsCallback(asyncResult) {
    const customProps = asyncResult.value;
    const myProp = customProps.get("myProp");

    customProps.set("otherProp", "value");
    customProps.saveAsync(saveCallback);
}

function saveCallback(asyncResult) {
}
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/15-item-custom-properties/load-set-get-save.yaml
Office.context.mailbox.item.loadCustomPropertiesAsync(function (result) {
  if (result.status === Office.AsyncResultStatus.Succeeded) {
    console.log("Loaded following custom properties:");
    customProps = result.value;
    const dataKey = Object.keys(customProps)[0];
    const data = customProps[dataKey];
    for (let propertyName in data)
    {
      let propertyValue = data[propertyName];
      console.log(`${propertyName}: ${propertyValue}`);
    }              
  }
  else {
    console.error(`loadCustomPropertiesAsync failed with message ${result.error.message}`);
  }
});

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

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

callback

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

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

Returns

void

Remarks

[ API set: Mailbox 1.7 ]

Minimum permission level: ReadItem

Applicable Outlook mode: Appointment Attendee

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 Item 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, asyncResult, which is an Office.AsyncResult object.

Returns

void

Remarks

[ API set: Mailbox 1.7 ]

Minimum permission level: ReadItem

Applicable Outlook mode: Appointment Attendee