Activation rules for contextual Outlook add-ins
Outlook activates some types of add-ins if the message or appointment that the user is reading or composing satisfies the activation rules of the add-in. This is true for all add-ins that use the 1.1 manifest schema. The user can then choose the add-in from the Outlook UI to start it for the current item.
Note
Outlook add-in features that depend on activation rules aren't supported when the add-in uses a unified app manifest for Microsoft 365.
Specify activation rules in a manifest
To have Outlook activate an add-in for specific conditions, specify activation rules in the add-in manifest by using one of the following Rule
elements.
- Rule element (MailApp complexType) - Specifies an individual rule.
- Rule element (RuleCollection complexType) - Combines multiple rules using logical operations.
Note
The Rule
element that you use to specify an individual rule is of the abstract Rule complex type. Each of the following types of rules extends this abstract Rule
complex type. So when you specify an individual rule in a manifest, you must use the xsi:type attribute to further define one of the following types of rules.
For example, the following rule defines an ItemIs rule.
<Rule xsi:type="ItemIs" ItemType="Message" />
The FormType
attribute applies to activation rules in the manifest v1.1 but is not defined in VersionOverrides
v1.0. So it can't be used when ItemIs is used in the VersionOverrides
node.
The following table lists the types of rules that are available. You can find more information following the table.
Rule name | Applicable forms | Description |
---|---|---|
ItemIs | Read, Compose | Checks to see whether the current item is of the specified type (message or appointment). Can also check the item class and form type, and optionally, item message class. |
ItemHasAttachment | Read | Checks to see whether the selected item contains an attachment. |
ItemHasRegularExpressionMatch | Read | Checks to see whether the sender's email address, the subject, or the body of the selected item contains a match to a regular expression. |
RuleCollection | Read, Compose | Combines a set of rules so that you can form more complex rules. |
Important
Entity-based contextual Outlook add-ins are now retired. As an alternative solution, implement regular expression rules in your contextual add-in. For guidance on how to implement these rules, see Contextual Outlook add-ins.
ItemIs rule
The ItemIs
complex type defines a rule that evaluates to true
if the current item matches the item type, and optionally the item message class if it's stated in the rule.
Specify one of the following item types in the ItemType
attribute of an ItemIs
rule. You can specify more than one ItemIs
rule in a manifest. The ItemType
attribute defines the types of Outlook items that support Outlook add-ins.
Value | Description |
---|---|
Appointment | Specifies an item in an Outlook calendar. This includes a meeting item that has been responded to and has an organizer and attendees, or an appointment that doesn't have an organizer or attendee and is simply an item on the calendar. This corresponds to the IPM.Appointment message class in Outlook. |
Message | Specifies one of the following items received in typically the Inbox.
|
The FormType
attribute is used to specify the mode (read or compose) in which the add-in should activate.
Note
The ItemIs FormType
attribute is defined in schema v1.1 and later, but not in VersionOverrides
v1.0. Don't include the FormType
attribute when defining add-in commands.
After an add-in is activated, you can use the mailbox.item property to obtain the currently selected item in Outlook, and the item.itemType property to obtain the type of the current item.
You can optionally use the ItemClass
attribute to specify the message class of the item, and the IncludeSubClasses
attribute to specify whether the rule should be true
when the item is a subclass of the specified class.
For more information about message classes, see Item Types and Message Classes.
The following example is an ItemIs
rule that activates the Outlook add-in when the user is reading a message.
<Rule xsi:type="ItemIs" ItemType="Message" FormType="Read" />
The following example is an ItemIs
rule that activates the Outlook add-in when the user is reading a message or appointment.
<Rule xsi:type="RuleCollection" Mode="Or">
<Rule xsi:type="ItemIs" ItemType="Message" FormType="Read" />
<Rule xsi:type="ItemIs" ItemType="Appointment" FormType="Read" />
</Rule>
ItemHasAttachment rule
The ItemHasAttachment
complex type defines a rule that checks if the selected item contains an attachment.
<Rule xsi:type="ItemHasAttachment" />
ItemHasRegularExpressionMatch rule
The ItemHasRegularExpressionMatch
complex type defines a rule that uses a regular expression to match the contents of the specified property of an item. Use the getRegExMatches
or getRegExMatchesByName
method of the object that represents the currently selected item to obtain matches for the specified regular expression.
The following example shows an ItemHasRegularExpressionMatch
that activates the add-in when the body of the selected item contains "apple", "banana", or "coconut", ignoring case.
<Rule xsi:type="ItemHasRegularExpressionMatch" RegExName="fruits" RegExValue="apple|banana|coconut" PropertyName="BodyAsPlaintext" IgnoreCase="true" />
For more information about using the ItemHasRegularExpressionMatch
rule, see Contextual Outlook add-ins.
RuleCollection rule
The RuleCollection
complex type combines multiple rules into a single rule. You can specify whether the rules in the collection should be combined with a logical OR or a logical AND by using the Mode
attribute.
When a logical AND is specified, an item must match all the specified rules in the collection to show the add-in. When a logical OR is specified, an item that matches any of the specified rules in the collection shows the add-in.
You can combine RuleCollection
rules to form complex rules. The following example activates the add-in when the user is viewing an appointment or message that contains an attachment.
<Rule xsi:type="RuleCollection" Mode="And">
<Rule xsi:type="RuleCollection" Mode="Or">
<Rule xsi:type="ItemIs" ItemType="Message" FormType="Read" />
<Rule xsi:type="ItemIs" ItemType="Appointment" FormType="Read" />
</Rule>
<Rule xsi:type="ItemHasAttachment" />
</Rule>
The following example activates the add-in when the user is composing a message, or when the user is viewing an appointment and its subject contains "sales", "marketing", or "finance".
<Rule xsi:type="RuleCollection" Mode="Or">
<Rule xsi:type="ItemIs" ItemType="Message" FormType="Edit" />
<Rule xsi:type="RuleCollection" Mode="And">
<Rule xsi:type="ItemIs" ItemType="Appointment" FormType="Read" />
<Rule xsi:type="ItemHasRegularExpressionMatch" RegExName="departments" RegExValue="sales|marketing|finance" PropertyName="Subject" IgnoreCase="true" />
</Rule>
</Rule>
Limits for rules and regular expressions
To provide a satisfactory experience with Outlook add-ins, you should adhere to the activation and API usage guidelines. To learn about these guidelines, see Limits for activation and JavaScript API for Outlook add-ins and Troubleshoot Outlook add-in activation.
See also
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