Office.Entities interface

Represents a collection of entities found in an email message or appointment. Read mode only.

The Entities object is a container for the entity arrays returned by the getEntities and getEntitiesByType methods when the item (either an email message or an appointment) contains one or more entities that have been found by the server. You can use these entities in your code to provide additional context information to the viewer, such as a map to an address found in the item, or to open a dialer for a phone number found in the item.

If no entities of the type specified in the property are present in the item, the property associated with that entity is null. For example, if a message contains a street address and a phone number, the addresses property and phoneNumbers property would contain information, and the other properties would be null.

To be recognized as an address, the string must contain a United States postal address that has at least a subset of the elements of a street number, street name, city, state, and zip code.

To be recognized as a phone number, the string must contain a North American phone number format.

Entity recognition relies on natural language recognition that is based on machine learning of large amounts of data. The recognition of an entity is non-deterministic and success sometimes relies on the particular context in the item.

When the property arrays are returned by the getEntitiesByType method, only the property for the specified entity contains data; all other properties are null.

Remarks

Minimum permission level: read item

Applicable Outlook mode: Read

Important: Entity-based contextual Outlook add-ins will be retired in Q2 of 2024. The work to retire this feature 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. The following APIs will also be retired.

  • Office.context.mailbox.item.getEntities - Office.context.mailbox.item.getEntitiesByType - Office.context.mailbox.item.getFilteredEntitiesByName - Office.context.mailbox.item.getSelectedEntities

To help minimize potential disruptions, the following will still be supported after entity-based contextual add-ins are retired.

  • An alternative implementation of the Join Meeting button, which is activated by online meeting add-ins, is being developed. Once support for entity-based contextual add-ins ends, online meeting add-ins will automatically transition to the alternative implementation to activate the Join Meeting button.

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

For more information, see Retirement of entity-based contextual Outlook add-ins.

Properties

addresses

Gets the physical addresses (street or mailing addresses) found in an email message or appointment.

contacts

Gets the contacts found in an email address or appointment.

emailAddresses

Gets the email addresses found in an email message or appointment.

meetingSuggestions

Gets the meeting suggestions found in an email message.

phoneNumbers

Gets the phone numbers found in an email message or appointment.

taskSuggestions

Gets the task suggestions found in an email message or appointment.

urls

Gets the Internet URLs present in an email message or appointment.

Property Details

addresses

Gets the physical addresses (street or mailing addresses) found in an email message or appointment.

addresses: string[];

Property Value

string[]

Examples

const item = Office.context.mailbox.item;
const addresses = item.getEntitiesByType(Office.MailboxEnums.EntityType.Address);

contacts

Gets the contacts found in an email address or appointment.

contacts: Contact[];

Property Value

Examples

const item = Office.context.mailbox.item;
const contacts = item.getEntitiesByType(Office.MailboxEnums.EntityType.Contact);

emailAddresses

Gets the email addresses found in an email message or appointment.

emailAddresses: string[];

Property Value

string[]

Examples

const item = Office.context.mailbox.item;
const emailAddresses = item.getEntitiesByType(Office.MailboxEnums.EntityType.EmailAddress);

meetingSuggestions

Gets the meeting suggestions found in an email message.

meetingSuggestions: MeetingSuggestion[];

Property Value

Examples

const item = Office.context.mailbox.item;
const meetingSuggestions = item.getEntitiesByType(Office.MailboxEnums.EntityType.MeetingSuggestion);

phoneNumbers

Gets the phone numbers found in an email message or appointment.

phoneNumbers: PhoneNumber[];

Property Value

Examples

const item = Office.context.mailbox.item;
const phoneNumbers = item.getEntitiesByType(Office.MailboxEnums.EntityType.PhoneNumber);

taskSuggestions

Gets the task suggestions found in an email message or appointment.

taskSuggestions: string[];

Property Value

string[]

Examples

const item = Office.context.mailbox.item;
const taskSuggestions = item.getEntitiesByType(Office.MailboxEnums.EntityType.TaskSuggestion);

urls

Gets the Internet URLs present in an email message or appointment.

urls: string[];

Property Value

string[]

Examples

const item = Office.context.mailbox.item;
const urls = item.getEntitiesByType(Office.MailboxEnums.EntityType.Url);