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. |
date |
Gets the date and time that an item was created. |
date |
Gets the date and time that an item was last modified. |
end | Gets the date and time that the appointment is to end. The When you use the |
item |
Gets the Exchange Web Services item class of the selected appointment. Returns |
item |
Gets the Exchange Web Services item identifier for the current item. The Note: The identifier returned by the |
item |
Gets the type of item that an instance represents. The |
location | Gets the location of an appointment. The |
normalized |
Gets the subject of an item, with all prefixes removed (including RE: and FWD:). The |
notification |
Gets the notification messages for an item. |
optional |
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
|
organizer | Gets the meeting organizer's email properties. |
required |
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
|
start | Gets the date and time that the appointment is to begin. The |
subject | Gets the description that appears in the subject field of an item. The The |
Methods
display |
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. |
display |
Displays a reply form that includes only the sender of the selected message or the organizer of the selected appointment. |
get |
Gets the entities found in the selected item's body. |
get |
Gets an array of all the entities of the specified entity type found in the selected item's body. |
get |
Returns well-known entities in the selected item that pass the named filter defined in an XML manifest file. |
get |
Returns string values in the selected item that match the regular expressions defined in an XML manifest file. |
get |
Returns string values in the selected item that match the named regular expression defined in an XML manifest file. |
load |
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 |
Property Details
attachments
Gets the item's attachments as an array.
attachments: AttachmentDetails[];
Property Value
Remarks
Minimum permission level: read item
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
Minimum permission level: read item
Applicable Outlook mode: Appointment Attendee
Examples
// This example gets the body of the item as plain text.
Office.context.mailbox.item.body.getAsync(
Office.CoercionType.Text,
{ asyncContext: "This is passed to the 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 message threads that appear below the current body)",
"status": "succeeded",
"asyncContext": "This is passed to the callback"
}
dateTimeCreated
Gets the date and time that an item was created.
dateTimeCreated: Date;
Property Value
Date
Remarks
Minimum permission level: read item
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.
dateTimeModified: Date;
Property Value
Date
Remarks
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}`);
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: read item
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}`);
itemClass
Gets the Exchange Web Services item class of the selected appointment.
Returns IPM.Appointment
for non-recurring appointments and IPM.Appointment.Occurrence
for recurring appointments.
itemClass: string;
Property Value
string
Remarks
Minimum permission level: read item
Applicable Outlook mode: Appointment Attendee
Important: You can create custom classes that extend a default item class. For example, IPM.Appointment.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}`);
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: read item
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
Office.MailboxEnums.ItemType | string
Remarks
Minimum permission level: read item
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: read item
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: read item
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
Minimum permission level: read item
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
// 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);
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. The maximum number of attendees returned varies per Outlook client.
Windows: 500 attendees
Android, classic Mac UI, iOS: 100 attendees
New Mac UI, web browser: No limit
optionalAttendees: EmailAddressDetails[];
Property Value
Remarks
Minimum permission level: read item
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: read item
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 + ")");
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. The maximum number of attendees returned varies per Outlook client.
Windows: 500 attendees
Android, classic Mac UI, iOS: 100 attendees
New Mac UI, web browser: No limit
requiredAttendees: EmailAddressDetails[];
Property Value
Remarks
Minimum permission level: read item
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
);
}
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: read item
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: read item
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
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.
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: read item
Applicable Outlook mode: Appointment Attendee
Important:
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.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>.");
displayReplyForm(formData)
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
- 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: read item
Applicable Outlook mode: Appointment Attendee
Important:
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.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.");
}
});
getEntities()
Gets the entities found in the selected item's body.
getEntities(): Entities;
Returns
Remarks
Minimum permission level: read item
Applicable Outlook mode: Appointment Attendee
Important:
Entity-based contextual Outlook add-ins, including the
getEntities
method, will be retired in Q2 of 2024. The work to retire this method will start in May and continue until the end of June. After June, contextual add-ins will no longer be able to detect entities in mail items to perform tasks on them. Regular expression rules will continue to be supported after entity-based contextual add-ins are retired. 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 Use regular expression activation rules to show an Outlook add-in. To learn more about the retirement of entity-based contextual Outlook add-ins, see Retirement of entity-based contextual Outlook add-ins.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/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.
getEntitiesByType(entityType: MailboxEnums.EntityType | string): Array<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 read item 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
Array<string | Office.Contact | Office.MeetingSuggestion | Office.PhoneNumber | Office.TaskSuggestion>
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
Important:
Entity-based contextual Outlook add-ins, including the
getEntitiesByType
method, will be retired in Q2 of 2024. The work to retire this method will start in May and continue until the end of June. After June, contextual add-ins will no longer be able to detect entities in mail items to perform tasks on them. Regular expression rules will continue to be supported after entity-based contextual add-ins are retired. 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 Use regular expression activation rules to show an Outlook add-in. To learn more about the retirement of entity-based contextual Outlook add-ins, see Retirement of entity-based contextual Outlook add-ins.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/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 an XML manifest file.
getFilteredEntitiesByName(name: string): Array<string | Contact | MeetingSuggestion | PhoneNumber | TaskSuggestion>;
Parameters
- name
-
string
The name of the ItemHasKnownEntity
rule element that defines the filter to match.
Returns
Array<string | Office.Contact | Office.MeetingSuggestion | Office.PhoneNumber | Office.TaskSuggestion>
The entities that match the regular expression defined in the ItemHasKnownEntity
rule element in the manifest XML 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
Minimum permission level: read item
Applicable Outlook mode: Appointment Attendee
Important:
Entity-based contextual Outlook add-ins, including the
getFilteredEntitiesByName
method, will be retired in Q2 of 2024. The work to retire this method will start in May and continue until the end of June. After June, contextual add-ins will no longer be able to detect entities in mail items to perform tasks on them. Regular expression rules will continue to be supported after entity-based contextual add-ins are retired. 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 Use regular expression activation rules to show an Outlook add-in. To learn more about the retirement of entity-based contextual Outlook add-ins, see Retirement of entity-based 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 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/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"));
getRegExMatches()
Returns string values in the selected item that match the regular expressions defined in an XML manifest file.
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. 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
Minimum permission level: read item
Applicable Outlook mode: Appointment Attendee
Important:
Entity-based contextual Outlook add-ins will be retired in Q2 of 2024. Once retired, contextual add-ins will no longer be able to detect entities in mail items to perform tasks on them. Regular expression rules will continue to be supported after entity-based contextual add-ins are retired. 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 Use regular expression activation rules to show an Outlook add-in. To learn more about the retirement of entity-based contextual add-ins, see Retirement of entity-based 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 theBody.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-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 an XML manifest file.
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 ItemHasRegularExpressionMatch
rule element in the manifest XML file, with the specified RegExName
element value.
Remarks
Minimum permission level: read item
Applicable Outlook mode: Appointment Attendee
Important:
Entity-based contextual Outlook add-ins will be retired in Q2 of 2024. Once retired, contextual add-ins will no longer be able to detect entities in mail items to perform tasks on them. Regular expression rules will continue to be supported after entity-based contextual add-ins are retired. 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 Use regular expression activation rules to show an Outlook add-in. To learn more about the retirement of entity-based contextual add-ins, see Retirement of entity-based 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 theBody.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-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"));
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 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
- 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
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: Appointment Attendee
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.");
});
Office Add-ins
Feedback
https://aka.ms/ContentUserFeedback.
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see:Submit and view feedback for