Limits for activation and JavaScript API for Outlook add-ins

Article
02/29/2024

To provide a satisfactory experience for users of Outlook add-ins, you should be aware of certain activation and API usage guidelines, and implement your add-ins to stay within these limits. These guidelines exist so that an individual add-in can't require Exchange Server or Outlook to spend an unusually long period of time to process its activation rules or calls to the Office JavaScript API, affecting the overall user experience for Outlook and other add-ins. These limits apply to designing activation rules in the add-in manifest, and using custom properties, roaming settings, recipients, Exchange Web Services (EWS) requests and responses, and asynchronous calls.

Note

You must also verify that your add-in performs within certain runtime resource usage limits. For more information, see Runtimes in Office Add-ins.

Limits on where add-ins activate

To learn more about where add-ins do and don't activate, see the "Mailbox items available to add-ins" section of Outlook add-ins overview.

Limits for JavaScript API

Each Outlook client enforces certain limits in the JavaScript object model, as described in the following table.

Feature	Limit	Related API	Description
Custom properties	2,500 characters	CustomProperties object Item.loadCustomPropertiesAsync method	Limit for all custom properties for an appointment or message item. All the Outlook clients return an error if the total size of all custom properties of an add-in exceeds this limit.
Roaming settings	32 KB number of characters	RoamingSettings object Context.roamingSettings property	Limit for all roaming settings for the add-in. All the Outlook clients return an error if your settings exceed this limit.
Internet headers	256 KB per message in Exchange Online Header size limit determined by the organization's administrators in Exchange on-premises	InternetHeaders.setAsync method	The total size limit of headers that can be applied to a message.
Extract well-known entities	2,000 number of characters	Item.getEntities method Item.getEntitiesByType method Item.getFilteredEntitiesByName method	Limit for Exchange Server to extract well-known entities on the item body. Exchange Server ignores entities beyond that limit. Note that this limit is independent of whether the add-in uses an `ItemHasKnownEntity` rule.
Exchange Web Services	5 MB number of characters in Outlook on the web, on Windows (starting in Version 2303 (Build 16225.10000)), on Mac (starting in Version 16.73 (23042601)), and in new Outlook on Windows (preview) 1 MB of characters in earlier versions of Outlook on Windows and on Mac	Mailbox.makeEwsRequestAsync method	Limit for a request or response to a `Mailbox.makeEwsRequestAsync` call.
Item multi-select	100 messages	Mailbox.getSelectedItemsAsync method	The maximum number of selected messages on which an Outlook add-in can activate.
Recipients	Varies across Outlook clients	Item.requiredAttendees property Item.optionalAttendees property Item.to property Item.cc property Recipients.addAsync method Recipients.getAsync method Recipients.setAsync method	Limit for the recipients specified in each property or method. To learn about the recipient limits for a specific Outlook client, see the API documentation for the property or method.
Display name	255 characters	EmailAddressDetails.displayName property Recipients object Item.requiredAttendees property Item.optionalAttendees property Item.to property Item.cc property	Limit for the length of a display name in an appointment or message.
Set the subject	255 characters	DisplayedSubject.setAsync (preview) Mailbox.displayNewAppointmentForm method Subject.setAsync method	Limit for the subject in the new appointment form, or for setting the subject of an appointment or message.
Set the location	255 characters	Location.setAsync method	Limit for setting the location of an appointment or meeting request.
Body in a new appointment form	32 KB number of characters	Mailbox.displayNewAppointmentForm method	Limit for the body in a new appointment form.
Display the body of an existing item	32 KB number of characters	Mailbox.displayAppointmentForm method Mailbox.displayMessageForm method	For Outlook on the web, mobile devices, and new Outlook on Windows (preview): limit for the body in an existing appointment or message form.
Set the body	1 MB number of characters	Body.prependAsync method Body.setAsync Body.setSelectedDataAsync method DisplayedBody.setAsync (preview)	Limit for setting the body of an appointment or message item.
Set the signature	30,000 characters	Body.setSignatureAsync method	Limit for the length of a signature in an appointment or message.
Number of attachments	499 files in Outlook on the web, on mobile devices, and in new Outlook on Windows (preview)	Item.addFileAttachmentAsync method	Limit for the number of files that can be attached to an item for sending. Outlook on the web and on mobile devices, and new Outlook on Windows (preview) generally limit attaching up to 499 files through the user interface and `addFileAttachmentAsync` method. Outlook on Windows and on Mac don't specifically limit the number of file attachments. However, all Outlook clients observe the limit for the size of attachments determined by the user's Exchange Server (see the "Size of attachments" row in this table).
Size of attachments	Dependent on Exchange Server	Item.addFileAttachmentAsync method	There's a limit on the size of all the attachments for a mail item, which an administrator can configure on the Exchange Server of the user's mailbox. For Outlook on Windows and on Mac, this limits the number of attachments for an item. For Outlook on the web and on mobile devices, and new Outlook on Windows (preview), the lesser of the two limits—the number of attachments and the size of all attachments—restricts the actual attachments for an item.
Attachment filename	255 characters	Item.addFileAttachmentAsync method	Limit for the length of the filename of an attachment to be added to an item.
Attachment URI	2,048 characters	Item.addFileAttachmentAsync method Item.addFileAttachmentFromBase64Async method	Limit of the URI of the filename to be added as an attachment to an item.
Base64-encoded string of an attachment	27,892,122 characters (about 25 MB)	Item.addFileAttachmentFromBase64Async method	Limit of the Base64-encoded string to be added as an attachment to an item.
Attachment ID	100 characters	Item.addItemAttachmentAsync method Item.removeAttachmentAsync method	Limit for the length of the ID of the attachment to be added to or removed from an item.
Asynchronous calls	3 calls	Item.addFileAttachmentAsync method Item.addItemAttachmentAsync method Item.removeAttachmentAsync method Body.getTypeAsync method Body.prependAsync method Body.setSelectedDataAsync method CustomProperties.saveAsync method Item.LoadCustomPropertiesAsync method Location.getAsync method Location.setAsync method Mailbox.getCallbackTokenAsync method Mailbox.getUserIdentityTokenAsync method Mailbox.makeEwsRequestAsync method Recipients.addAsync method Recipients.getAsync method Recipients.setAsync method RoamingSettings.saveAsync method Subject.getAsync method Subject.setAsync method Time.getAsync method Time.setAsync method	For Outlook on the web and on mobile devices, and new Outlook on Windows (preview): limit of the number of simultaneous asynchronous calls at any one time, as browsers allow only a limited number of asynchronous calls to servers.
Append-on-send	5,000 characters	Body.appendOnSendAsync method	Limit of the content to be appended to a message or appointment body on send.
Prepend-on-send	5,000 characters	Body.prependOnSendAsync method	Limit of the content to be prepended to a message or appointment body on send.

Limits of activation rules for contextual Outlook add-ins

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.

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.

Follow these guidelines when designing activation rules for contextual Outlook add-ins.

Limit the size of the manifest to 256 KB. You can't install the Outlook add-in for an Exchange mailbox if you exceed that limit.

Note

Outlook add-in features that depend on activation rules aren't supported when the add-in uses a Unified manifest for Microsoft 365 (preview).
Specify up to 15 activation rules for the add-in. You can't install the add-in if you exceed that limit.
In Outlook on Windows and on Mac, if you use an ItemHasKnownEntity rule on the body of the selected item, expect the rule to be only applied against the first 1 MB of the body and not to the rest of the body over that limit. Your add-in won't activate if matches exist only after the first MB of the body. If you expect that to be a likely scenario, redesign your conditions for activation.
If you use regular expressions in ItemHasKnownEntity or ItemHasRegularExpressionMatch rules, be aware of the following limits and guidelines that generally apply to any Outlook application and those described in the tables of the succeeding sections that differ depending on the application.
- Specify up to only five regular expressions in activation rules in an add-in. You can't install an add-in if you exceed that limit.
- Specify regular expressions such that the results you anticipate are returned by the getRegExMatches method call within the first 50 matches.
- Important: Text is highlighted based on strings that result from matching the regular expression. However, the highlighted occurrences may not exactly match what should result from actual regular expression assertions like negative look-ahead (?!text), look-behind (?<=text), and negative look-behind (?<!text). For example, if you use the regular expression under(?!score) on "Like under, under score, and underscore", the string "under" is highlighted for all occurrences instead of just the first two.

Differences in the support for regular expressions

The following table lists the limits and describes the differences in the support for regular expressions across Outlook clients. The support is independent of any specific type of device and item body.

Outlook on Windows and on Mac	Outlook on the web, on mobile devices, and on new Windows client (preview)
Clients use the C++ regular expression engine provided as part of the Visual Studio standard template library. This engine complies with ECMAScript 5 standards.	Clients use regular expression evaluation that's part of JavaScript. It's provided by the browser and supports a superset of ECMAScript 5.
Because of the different regex engines, a regex that includes a custom character class based on predefined character classes may return different results in Outlook on Windows and on Mac versus in Outlook on the web, on mobile devices, and in new Outlook on Windows (preview). As an example, the regex `[\s\S]{0,100}` matches any number, between 0 and 100, of single characters that is a whitespace or a non-whitespace. This regex returns different results depending on your Outlook client. As a workaround, you should rewrite the regex as `(\s\\|\S){0,100}`. This regex matches any number, between 0 and 100, of white space or non-white space. You should test each regex thoroughly on each Outlook client. If a regex returns different results, rewrite the regex.	You should test each regex thoroughly on each Outlook client. If a regex returns different results, rewrite the regex.
By default, the evaluation of all regular expressions for an add-in is limited to one second. Exceeding this limit causes reevaluation of up to three times. Beyond the reevaluation limit, Outlook on Windows and on Mac prevent the add-in from running for the same mailbox in any of the Outlook clients. Administrators can override these evaluation limits by using the `OutlookActivationAlertThreshold` and `OutlookActivationManagerRetryLimit` registry keys.	The resource monitoring and registry settings supported in Outlook on Windows and on Mac aren't supported in Outlook on the web, on mobile devices, and in new Outlook on Windows (preview). However, add-ins with regular expressions that require excessive amount of evaluation time in Outlook on Windows and on Mac are disabled for the same mailbox on all the Outlook clients.

Limits on the size of the item body evaluated

The following table lists the limits and describes the differences in the portion of the item body to which each Outlook client applies a regular expression. Some of these limits depend on the type of device and item body, if the regular expression is applied on the item body.

	Outlook on Windows and on Mac	Outlook on mobile devices	Outlook on the web and on new Windows client (preview)
Form factor	Any supported device.	Android smartphones, iPad, or iPhone.	Any supported device other than Android smartphones, iPad, and iPhone.
Plain text item body	Applies the regex on the first 1 MB of the data of the body, but not on the rest of the body over that limit.	Activates the add-in only if the body < 16,000 characters.	Activates the add-in only if the body < 500,000 characters.
HTML item body	Applies the regex on the first 512 KB of the data of the body, but not on the rest of the body over that limit. (The actual number of characters depends on the encoding which can range from 1 to 4 bytes per character.)	Applies the regex on the first 64,000 characters (including HTML tag characters), but not on the rest of the body over that limit.	Activates the add-in only if the body < 500,000 characters.

Limits on the matches returned

The following table lists the limits and describes the differences in the matches that each Outlook client returns after evaluating a regular expression. The support is independent of any specific type of device, but may depend on the type of item body, if the regular expression is applied on the item body.

	Outlook on Windows and on Mac	Outlook on the web, on mobile devices, and on new Windows client (preview)
Order of returned matches	Assume the `getRegExMatches` method returns different matches for the same regular expression applied on the same mail item in Outlook on Windows and on Mac versus in Outlook on the web, on mobile devices, and in new Outlook on Windows (preview).	Assume the `getRegExMatches` method returns different matches for the same regular expression applied on the same mail item in Outlook on Windows and on Mac versus in Outlook on the web, on mobile devices, and in new Outlook on Windows (preview).
Plain text item body	The `getRegExMatches` method returns any matches that are up to 1,536 (1.5 KB) characters, for a maximum of 50 matches. Note: `getRegExMatches` doesn't return matches in any specific order in the returned array. In general, assume the order of matches for the same regular expression applied on the same mail item in Outlook on Windows and on Mac is different from that in Outlook on the web, on mobile devices, and in new Outlook on Windows (preview).	`getRegExMatches` returns any matches that are up to 3,072 (3 KB) characters, for a maximum of 50 matches.
HTML item body	`getRegExMatches` returns any matches that are up to 3,072 (3 KB) characters, for a maximum of 50 matches. Note: `getRegExMatches` doesn't return matches in any specific order in the returned array. In general, assume the order of matches for the same regular expression applied on the same mail item in Outlook on Windows and on Mac is different from that in Outlook on the web, on mobile devices, and in new Outlook on Windows (preview).	`getRegExMatches` returns any matches that are up to 3,072 (3 KB) characters, for a maximum of 50 matches.