Office.MessageRead interface

Gets the item's attachments as an array.

attachments: AttachmentDetails[];

Property Value

Remarks

Minimum permission level: read item

Applicable Outlook mode: Message Read

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);

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

Applicable Outlook mode: Message Read

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"
}

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

Applicable Outlook mode: Message Read

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);
  }
});

...

// 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);
  }
});

...

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);
  }
});

Provides access to the Cc (carbon copy) recipients of a message. The type of object and level of access depend on the mode of the current item.

The cc property returns an array that contains an EmailAddressDetails object for each recipient listed on the Cc line of the message. The maximum number of recipients returned varies per Outlook client.

• classic Windows: 500 recipients

• Android, classic Mac UI, iOS: 100 recipients

• Web browser, new Outlook: 20 recipients (collapsed view), 500 recipients (expanded view)

• New Mac UI: No limit

cc: EmailAddressDetails[];

Property Value

Remarks

Minimum permission level: read item

Applicable Outlook mode: Message Read

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/30-recipients-and-attendees/get-cc-message-read.yaml

const msgCc = Office.context.mailbox.item.cc;
console.log("Message copied to:");
for (let i = 0; i < msgCc.length; i++) {
  console.log(msgCc[i].displayName + " (" + msgCc[i].emailAddress + ")");
}

Gets an identifier for the email conversation that contains a particular message.

You can get an integer for this property if your mail app is activated in read forms or responses in compose forms. If subsequently the user changes the subject of the reply message, upon sending the reply, the conversation ID for that message will change and that value you obtained earlier will no longer apply.

You get null for this property for a new item in a compose form. If the user sets a subject and saves the item, the conversationId property will return a value.

conversationId: string;

Property Value

Remarks

Minimum permission level: read item

Applicable Outlook mode: Message Read

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/90-other-item-apis/get-conversation-id-message.yaml

console.log(`Conversation ID: ${Office.context.mailbox.item.conversationId}`);

Gets the date and time that an item was created.

dateTimeCreated: Date;

Property Value

Remarks

Minimum permission level: read item

Applicable Outlook mode: Message Read

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}`);

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

dateTimeModified: Date;

Property Value

Remarks

[ API set: Mailbox 1.1 ]

Minimum permission level: read item

Applicable Outlook mode: Appointment Attendee

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

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}`);

Gets an object to temporarily set the content displayed in the body or subject of a message in read mode.

display: Display;

Property Value

Remarks

[ API set: Mailbox preview ]

Minimum permission level: read/write item

Applicable Outlook mode: Message Read

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/99-preview-apis/set-displayed-body-subject.yaml

// This snippet temporarily sets the content displayed in the body of a message in read mode.
// The set content will remain visible until the user switches to a different message in the Reading Pane or closes the window of the current message.
const bodyText = $("#body-text-field")
  .val()
  .toString();
Office.context.mailbox.item.display.body.setAsync(bodyText, (asyncResult) => {
  if (asyncResult.status === Office.AsyncResultStatus.Failed) {
    console.log(`Action failed with error: ${asyncResult.error.message}`);
    return;
  }

  console.log("Temporarily set the content displayed in the body.");
});

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

Remarks

Minimum permission level: read item

Applicable Outlook mode: Message Read

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}`);

Gets the email address of the sender of a message.

The from and sender properties represent the same person unless the message is sent by a delegate. In that case, the from property represents the delegator, and the sender property represents the delegate.

Note: The recipientType property of the EmailAddressDetails object in the from property is undefined.

The from property returns an EmailAddressDetails object.

from: EmailAddressDetails;

Property Value

Remarks

Minimum permission level: read item

Applicable Outlook mode: Message Read

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/30-recipients-and-attendees/get-from-message-read.yaml

const msgFrom = Office.context.mailbox.item.from;
console.log("Message received from: " + msgFrom.displayName + " (" + msgFrom.emailAddress + ")");

Gets the internet message identifier for an email message.

Important: In the Sent Items folder, the internetMessageId may not be available yet on recently sent items. In that case, consider using Exchange Web Services to get this property from the server.

internetMessageId: string;

Property Value

Remarks

Minimum permission level: read item

Applicable Outlook mode: Message Read

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/90-other-item-apis/get-internet-message-id-read.yaml

console.log(`Internet message ID: ${Office.context.mailbox.item.internetMessageId}`);

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

itemClass: string;

Property Value

Remarks

Minimum permission level: read item

Applicable Outlook mode: Message Read

Important:

The following table lists the default item classes for messages.

You can create custom classes that extend a default item class. For example, IPM.Note.Contoso.

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}`);

Gets the Exchange Web Services (EWS) item identifier of the current item.

itemId: string;

Property Value

Remarks

Minimum permission level: read item

Applicable Outlook mode: Message Read

Important:

• The itemId property isn't available in compose mode. If an item identifier is required, the Office.context.mailbox.item.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. If the item is already saved, you can call the Office.context.mailbox.item.getItemIdAsync method instead.

• The item ID returned isn't 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.

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;
    });
}

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

Applicable Outlook mode: Message Read

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;
}

Gets the location of a meeting request.

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

location: string;

Property Value

Remarks

Minimum permission level: read item

Applicable Outlook mode: Message Read

Examples

// 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}`);

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

Remarks

Minimum permission level: read item

Applicable Outlook mode: Message Read

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}`);

Gets the notification messages for an item.

notificationMessages: NotificationMessages;

Property Value

Remarks

[ API set: Mailbox 1.3 ]

Minimum permission level: read item

Applicable Outlook mode: Message Read

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/35-notifications/add-getall-remove.yaml

// Adds a progress indicator to the mail item.
const id = $("#notificationId").val().toString();
const details =
  {
    type: Office.MailboxEnums.ItemNotificationMessageType.ProgressIndicator,
    message: "Progress indicator with id = " + id
  };
Office.context.mailbox.item.notificationMessages.addAsync(id, details, handleResult);

...

// Adds an informational notification to the mail item.
const id = $("#notificationId").val().toString();
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);

...

// Adds a persistent information notification to the mail item.
const id = $("#notificationId").val().toString();
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);

...

// Gets all the notification messages and their keys for the current mail item.
Office.context.mailbox.item.notificationMessages.getAllAsync((asyncResult) => {
  if (asyncResult.status === Office.AsyncResultStatus.Failed) {
    console.log(asyncResult.error.message);
    return;
  }

  console.log(asyncResult.value);
});

...

// Replaces a notification message of a given key with another message.
const id = $("#notificationId").val().toString();
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);

...

// Removes a notification message from the current mail item.
const id = $("#notificationId").val().toString();
Office.context.mailbox.item.notificationMessages.removeAsync(id, handleResult);

Gets the recurrence pattern of an appointment. Gets the recurrence pattern of a meeting request. Read and compose modes for appointment items. Read mode for meeting request items.

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. undefined is returned for messages that are not meeting requests.

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

Applicable Outlook mode: Message Read

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));
}

Gets the email address of the sender of an email message.

The from and sender properties represent the same person unless the message is sent by a delegate. In that case, the from property represents the delegator, and the sender property represents the delegate.

Note: The recipientType property of the EmailAddressDetails object in the sender property is undefined.

sender: EmailAddressDetails;

Property Value

Remarks

Minimum permission level: read item

Applicable Outlook mode: Message Read

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/30-recipients-and-attendees/get-sender-message-read.yaml

const msgSender = Office.context.mailbox.item.sender;
console.log("Sender: " + msgSender.displayName + " (" + msgSender.emailAddress + ")");

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

In Outlook on the web, on Windows (new and classic), and on Mac, the seriesId returns the Exchange Web Services (EWS) ID of the parent (series) item that this item belongs to. However, in Outlook on Android and on iOS, 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 don't have parent items such as single appointments, series items, or meeting requests and returns undefined for any other items that aren't meeting requests.

seriesId: string;

Property Value

Remarks

[ API set: Mailbox 1.7 ]

Minimum permission level: read item

Applicable Outlook mode: Message Read

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);
}

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

Remarks

Minimum permission level: read item

Applicable Outlook mode: Message Read

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}`);

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

Remarks

Minimum permission level: read item

Applicable Outlook mode: Message Read

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}`);

Provides access to the recipients on the To line of a message. The type of object and level of access depend on the mode of the current item.

The to property returns an array that contains an EmailAddressDetails object for each recipient listed on the To line of the message. The maximum number of recipients returned varies per Outlook client.

• classic Windows: 500 recipients

• Android, classic Mac UI, iOS: 100 recipients

• Web browser, new Outlook: 20 recipients (collapsed view), 500 recipients (expanded view)

• New Mac UI: No limit

to: EmailAddressDetails[];

Property Value

Remarks

Minimum permission level: read item

Applicable Outlook mode: Message Read

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/30-recipients-and-attendees/get-to-message-read.yaml

const msgTo = Office.context.mailbox.item.to;
const distributionLists = [];
const externalRecipients = [];
const internalRecipients = [];
const otherRecipients = [];
for (let i = 0; i < msgTo.length; i++) {
    switch (msgTo[i].recipientType) {
    case Office.MailboxEnums.RecipientType.DistributionList:
        distributionLists.push(msgTo[i]);
        break;
    case Office.MailboxEnums.RecipientType.ExternalUser:
        externalRecipients.push(msgTo[i]);
        break;
    case Office.MailboxEnums.RecipientType.User:
        internalRecipients.push(msgTo[i]);
        break;
    case Office.MailboxEnums.RecipientType.Other:
        otherRecipients.push(msgTo[i]);
    }
}

if (distributionLists.length > 0) {
    console.log("Distribution Lists:");
    distributionLists.forEach((recipient) => console.log(`${recipient.displayName}, ${recipient.emailAddress}`));
}

if (externalRecipients.length > 0) {
    console.log("External Recipients:");
    externalRecipients.forEach((recipient) => console.log(`${recipient.displayName}, ${recipient.emailAddress}`));
}

if (internalRecipients.length > 0) {
    console.log("Internal Recipients:");
    internalRecipients.forEach((recipient) => console.log(`${recipient.displayName}, ${recipient.emailAddress}`));
}

if (otherRecipients.length > 0) {
    console.log("Other Recipients:");
    otherRecipients.forEach((recipient) => console.log(`${recipient.displayName}, ${recipient.emailAddress}`));
}

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

Returns

Remarks

[ API set: Mailbox 1.7 ]

Minimum permission level: read item

Applicable Outlook mode: Message Read

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);

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

Returns

Remarks

[ API set: Mailbox 1.7 ]

Minimum permission level: read item

Applicable Outlook mode: Message Read

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.

displayReplyAllForm(formData: string | ReplyFormData): void;

Parameters

Returns

Remarks

[ API set: Mailbox 1.1 ]

Minimum permission level: read item

Applicable Outlook mode: Appointment Attendee

Important:

• In Outlook on the web and new Outlook on Windows, 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.

• 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

// 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>.");

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.

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

Parameters

Returns

Remarks

[ API set: Mailbox 1.9 ]

Minimum permission level: read item

Applicable Outlook mode: Message Read

Important:

• In Outlook on the web and new Outlook on Windows, 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.

• 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-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));
});

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.

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

Parameters

Returns

Remarks

[ API set: Mailbox 1.9 ]

Minimum permission level: read item

Applicable Outlook mode: Message Read

Important:

• In Outlook on the web and new Outlook on Windows, 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.

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

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

displayReplyForm(formData: string | ReplyFormData): void;

Parameters

Returns

Remarks

[ API set: Mailbox 1.1 ]

Minimum permission level: read item

Applicable Outlook mode: Message Read

Important:

• In Outlook on the web and new Outlook on Windows, 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.

• 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-reply-forms.yaml

Office.context.mailbox.item.displayReplyForm("This is a reply with <i>some text in italics</i>.");

...

Office.context.mailbox.item.displayReplyForm({
  htmlBody: "This is a reply with an inline image and an item attachment.<br><img src='cid:dog.jpg'>",
  attachments: [
    { type: "file", url: "https://i.imgur.com/9S36xvA.jpg", name: "dog.jpg", inLine: true },
    { type: "item", itemId: Office.context.mailbox.item.itemId, name: "test_email.msg" }
  ],
  callback: (result) => {
    if (result.status === Office.AsyncResultStatus.Failed) {
      console.error(`Action failed with message ${result.error.message}`);
      return;
    }

    console.log("Created reply with attachments.");
  }
});

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

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

Parameters

Returns

Remarks

[ API set: Mailbox 1.9 ]

Minimum permission level: read item

Applicable Outlook mode: Message Read

Important:

• In Outlook on the web and new Outlook on Windows, 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.

• 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-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));
});

...

// The async version is only available starting with requirement set 1.9.
// It provides a callback when the new appointment form has been created.
Office.context.mailbox.item.displayReplyFormAsync(
  {
    htmlBody: "This is a reply with an inline image and an item attachment.<br><img src='cid:dog.jpg'>",
    attachments: [
      { type: "file", url: "http://i.imgur.com/9S36xvA.jpg", name: "dog.jpg", inLine: true },
      { type: "item", itemId: Office.context.mailbox.item.itemId, name: "test_email.msg" }
    ]
  },
  (asyncResult) => {
    console.log(JSON.stringify(asyncResult));
  }
);

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

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

Parameters

Returns

Remarks

[ API set: Mailbox 1.9 ]

Minimum permission level: read item

Applicable Outlook mode: Message Read

Important:

• In Outlook on the web and new Outlook on Windows, 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.

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

Gets all the internet headers for the message as a string.

To learn more, see Get and set internet headers on a message in an Outlook add-in.

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

Parameters

Returns

Remarks

[ API set: Mailbox 1.8 ]

Minimum permission level: read item

Applicable Outlook mode: Message Read

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/70-mime-headers/get-internet-headers-message-read.yaml

Office.context.mailbox.item.getAllInternetHeadersAsync(function (asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    console.log("Internet headers received successfully");
    if (asyncResult.value.match(/preferred-fruit:.*/gim)) {
      console.log("Sender's preferred fruit: " + asyncResult.value.match(/preferred-fruit:.*/gim)[0].slice(17));
    } else {
      console.log("Didn't receive header with sender's preferred fruit");
    }
    if (asyncResult.value.match(/preferred-vegetable:.*/gim)) {
      console.log(
        "Sender's preferred vegetable: " + asyncResult.value.match(/preferred-vegetable:.*/gim)[0].slice(21)
      );
    } else {
      console.log("Didn't receive header with sender's preferred vegetable");
    }
  } else {
    console.log("Error getting internet headers: " + JSON.stringify(asyncResult.error));
  }
});

Gets all the internet headers for the message as a string.

To learn more, see Get and set internet headers on a message in an Outlook add-in.

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

Parameters

Returns

Remarks

[ API set: Mailbox 1.8 ]

Minimum permission level: read item

Applicable Outlook mode: Message Read

Gets the current message in EML format encoded in Base64.

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

Parameters

Returns

Remarks

[ API set: Mailbox 1.14 ]

Minimum permission level: read item

Applicable Outlook mode: Message Read

Gets the current message in EML format encoded in Base64.

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

Parameters

Returns

Remarks

[ API set: Mailbox 1.14 ]

Minimum permission level: read item

Applicable Outlook mode: Message Read

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/90-other-item-apis/get-eml-format.yaml

Office.context.mailbox.item.getAsFileAsync((asyncResult) => {
  if (asyncResult.status === Office.AsyncResultStatus.Failed) {
    console.log(`Error encountered during processing: ${asyncResult.error.message}`);
    return;
  }

  console.log(asyncResult.value);
});

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, on mobile devices, and in new Outlook on Windows, 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

Returns

Remarks

[ API set: Mailbox 1.8 ]

Minimum permission level: read item

Applicable Outlook mode: Message Read

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);
}

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, on mobile devices, and in new Outlook on Windows, 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

Returns

Remarks

[ API set: Mailbox 1.8 ]

Minimum permission level: read item

Applicable Outlook mode: Message Read

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.

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

Warning: Entity-based contextual Outlook add-ins are now retired. However, regular expression rules are still supported. We recommend updating your contextual add-in to use regular expression rules as an alternative solution. For guidance on how to implement these rules, see Contextual Outlook add-ins.

getEntities(): Entities;

Returns

Remarks

[ API set: Mailbox 1.1 ]

Minimum permission level: read item

Applicable Outlook mode: Appointment Attendee

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

Warning: Entity-based contextual Outlook add-ins are now retired. However, regular expression rules are still supported. We recommend updating your contextual add-in to use regular expression rules as an alternative solution. For guidance on how to implement these rules, see Contextual Outlook add-ins.

getEntitiesByType(entityType: MailboxEnums.EntityType | string): Array<string | Contact | MeetingSuggestion | PhoneNumber | TaskSuggestion>;

Parameters

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

[ API set: Mailbox 1.1 ]

Minimum permission level: restricted

Applicable Outlook mode: Message Read

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

Warning: Entity-based contextual Outlook add-ins are now retired. However, regular expression rules are still supported. We recommend updating your contextual add-in to use regular expression rules as an alternative solution. For guidance on how to implement these rules, see Contextual Outlook add-ins.

getFilteredEntitiesByName(name: string): Array<string | Contact | MeetingSuggestion | PhoneNumber | TaskSuggestion>;

Parameters

Returns

The entities that match the regular expression defined in the ItemHasKnownEntity rule element in the add-in manifest file with the specified FilterName element value. If there's 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 returns an empty array.

Remarks

[ API set: Mailbox 1.1 ]

Minimum permission level: read item

Applicable Outlook mode: Appointment Attendee

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

Returns

Remarks

[ API set: Mailbox 1.8 ]

Minimum permission level: read item

Applicable Outlook mode: Message Read

Examples

// Get the initialization context (if present).
Office.context.mailbox.item.getInitializationContextAsync((asyncResult) => {
    if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
        if (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 {
        // Handle the error.
    }
});

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

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

Parameters

Returns

Remarks

[ API set: Mailbox 1.8 ]

Minimum permission level: read item

Applicable Outlook mode: Message Read

Returns string values in the selected item that match the regular expressions defined in an add-in only manifest file.

getRegExMatches(): any;

Returns

An object that contains arrays of strings that match the regular expressions defined in the add-in manifest file. The name of each array is equal to the corresponding value of the RegExName attribute of the matching ItemHasRegularExpressionMatch rule. For an ItemHasRegularExpressionMatch rule, a matching string has to occur in the property of the item that's specified by that rule. The PropertyName simple type defines the supported properties.

Remarks

[ API set: Mailbox 1.1 ]

Minimum permission level: read item

Applicable Outlook mode: Appointment Attendee

Important:

• Entity-based contextual Outlook add-ins are now retired. However, regular expression rules are still supported. We recommend updating your contextual add-in to use regular expression rules as an alternative solution. For guidance on how to implement these rules, see Contextual Outlook add-ins.

• This method is used with the activation rules feature for Outlook add-ins, which isn't supported by the unified manifest for Microsoft 365.

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

• 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

// 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-regex-matches/contextual.yaml

// This API only works when you click on the highlighted word "ScriptLab".
console.log(Office.context.mailbox.item.getRegExMatches());

Returns string values in the selected item that match the named regular expression defined in an add-in only manifest file.

getRegExMatchesByName(name: string): string[];

Parameters

Returns

An array that contains the strings that match the regular expression defined in the ItemHasRegularExpressionMatch rule element in the add-in manifest file, with the specified RegExName element value.

Remarks

[ API set: Mailbox 1.1 ]

Minimum permission level: read item

Applicable Outlook mode: Appointment Attendee

Important:

• Entity-based contextual Outlook add-ins are now retired. However, regular expression rules are still supported. We recommend updating your contextual add-in to use regular expression rules as an alternative solution. For guidance on how to implement these rules, see Contextual Outlook add-ins.

• This method is used with the activation rules feature for Outlook add-ins, which isn't supported by the unified manifest for Microsoft 365.

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

• 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

// 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-regex-matches/contextual.yaml

// This API only works when you click on the highlighted word "ScriptLab".
console.log(Office.context.mailbox.item.getRegExMatchesByName("sampleRegexName"));

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

Warning: Entity-based contextual Outlook add-ins are now retired. However, regular expression rules are still supported. We recommend updating your contextual add-in to use regular expression rules as an alternative solution. For guidance on how to implement these rules, see Contextual Outlook add-ins.

getSelectedEntities(): Entities;

Returns

Remarks

[ API set: Mailbox 1.6 ]

Minimum permission level: read item

Applicable Outlook mode: Message Read

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

getSelectedRegExMatches(): any;

Returns

An object that contains arrays of strings that match the regular expressions defined in the add-in manifest file. The name of each array is equal to the corresponding value of the RegExName attribute of the matching ItemHasRegularExpressionMatch rule. For an ItemHasRegularExpressionMatch rule, a matching string has to occur in the property of the item that's specified by that rule. The PropertyName simple type defines the supported properties.

Remarks

[ API set: Mailbox 1.6 ]

Minimum permission level: read item

Applicable Outlook mode: Message Read

Important:

• Entity-based contextual Outlook add-ins are now retired. However, regular expression rules are still supported. We recommend updating your contextual add-in to use regular expression rules as an alternative solution. For guidance on how to implement these rules, see Contextual Outlook add-ins.

• This method is used with the activation rules feature for Outlook add-ins, which isn't supported by the unified manifest for Microsoft 365.

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

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

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-regex-matches/contextual.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.");
}

Gets the properties of an appointment or message in a shared folder or shared mailbox.

For more information around using this API, see Enable shared folders and shared mailbox scenarios in an Outlook add-in.

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

Parameters

Returns

Remarks

[ API set: Mailbox 1.8 for shared folder support, Mailbox 1.13 for shared mailbox support ]

Minimum permission level: read item

Applicable Outlook mode: Message Read

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

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 Enable shared folders and shared mailbox scenarios in an Outlook add-in.

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

Parameters

Returns

Remarks

[ API set: Mailbox 1.8 for shared folder support, Mailbox 1.13 for shared mailbox support ]

Minimum permission level: read item

Applicable Outlook mode: Message Read

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

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

Office.context.mailbox.item.getSharedPropertiesAsync((result) => {
  if (result.status === Office.AsyncResultStatus.Failed) {
    console.error("The current folder or mailbox isn't shared.");
    return;
  }
  const sharedProperties = result.value;
  console.log(`Owner: ${sharedProperties.owner}`);
  console.log(`Permissions: ${sharedProperties.delegatePermissions}`);
  console.log(`Target mailbox: ${sharedProperties.targetMailbox}`);
});

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 aren't encrypted on the item, so this shouldn't 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, save, and remove custom properties from the mail item.

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

Parameters

Returns

Remarks

[ API set: Mailbox 1.1 ]

To learn more about custom properties, see Get and set add-in metadata for an Outlook add-in.

Minimum permission level: read item

Applicable Outlook mode: Message Read

Examples

// 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((result) => {
  if (result.status === Office.AsyncResultStatus.Failed) {
    console.error(`loadCustomPropertiesAsync failed with message ${result.error.message}`);
    return;
  }

  customProps = result.value;
  console.log("Loaded the CustomProperties object.");
});

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

Returns

Remarks

[ API set: Mailbox 1.7 ]

Minimum permission level: read item

Applicable Outlook mode: Message Read

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

Returns

Remarks

[ API set: Mailbox 1.7 ]

Minimum permission level: read item

Applicable Outlook mode: Message Read

Examples

Office.context.mailbox.item.removeHandlerAsync(Office.EventType.ItemChanged, (asyncResult) => {
    if (asyncResult.status === Office.AsyncResultStatus.Failed) {
        console.error("Failed to remove event handler: " + asyncResult.error.message);
        return;
    }

    console.log("Event handler removed successfully.");
});