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. |
email |
Gets the email addresses found in an email message or appointment. |
meeting |
Gets the meeting suggestions found in an email message. |
phone |
Gets the phone numbers found in an email message or appointment. |
task |
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);
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