Limits for activation and JavaScript API for Outlook add-ins

Artikkeli
07/18/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.
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 1 MB of characters in earlier versions of Outlook on Windows (classic) 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: 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 and new Outlook on Windows	Item.addFileAttachmentAsync method	Limit for the number of files that can be attached to an item for sending. Outlook on the web and new Outlook on Windows generally limit attaching up to 499 files through the user interface and `addFileAttachmentAsync` method. Outlook on Windows (classic) and on Mac don't specifically limit the number of file attachments. However, all Outlook clients observe the limit for the size of attachments (see the "Size of attachments" row in this table).
Size of attachments	Dependent on Exchange Server in classic Outlook on Windows and Outlook on Mac 25 MB in Outlook on the web and new Outlook on Windows	Item.addFileAttachmentAsync method	Limit for the size of all the attachments added to a mail item. In classic Outlook on Windows and Outlook on Mac, the limit is configured by an administrator on the Exchange Server of the user's mailbox. In these clients, this also limits the number of attachments of an item. For Outlook on the web and new Outlook on Windows, the lesser of the two limits—the number of attachments and the size of all attachments—restricts the actual attachments of 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: 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 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.

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 app manifest for Microsoft 365.
Specify up to 15 activation rules for the add-in. You can't install the add-in if you exceed that limit.
When you use regular expressions in the ItemHasRegularExpressionMatch rule, 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 the web, on new Windows client, and on mobile devices	Outlook on Windows (classic) and on Mac
Clients use regular expression evaluation that's part of JavaScript. It's provided by the browser and supports a superset of ECMAScript 5.	Clients use the C++ regular expression engine provided as part of the Visual Studio standard template library. This engine complies with ECMAScript 5 standards.
You should test each regex thoroughly on each Outlook client. If a regex returns different results, rewrite the regex.	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 (classic) and on Mac versus in Outlook on the web, on mobile devices, and in new Outlook on Windows. 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.
The resource monitoring and registry settings supported in Outlook on Windows (classic) and on Mac aren't supported in Outlook on the web, on mobile devices, and in new Outlook on Windows. However, add-ins with regular expressions that require excessive amount of evaluation time in Outlook on Windows (classic) and on Mac are disabled for the same mailbox on all the Outlook clients.	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 (classic) 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.

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 the web and on new Windows client	Outlook on Windows (classic) and on Mac	Outlook on mobile devices
Form factor	Any supported device other than Android smartphones, iPad, and iPhone.	Any supported device.	Android smartphones, iPad, or iPhone.
Plain text item body	Activates the add-in only if the body < 500,000 characters.	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.
HTML item body	Activates the add-in only if the body < 500,000 characters.	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.

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 the web, on new Windows client, and on mobile devices	Outlook on Windows (classic) and on Mac
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 (classic) and on Mac versus in Outlook on the web, on mobile devices, and in new Outlook on Windows.	Assume the `getRegExMatches` method returns different matches for the same regular expression applied on the same mail item in Outlook on Windows (classic) and on Mac versus in Outlook on the web, on mobile devices, and in new Outlook on Windows.
Plain text item body	`getRegExMatches` returns any matches that are up to 3,072 (3 KB) characters, for a maximum of 50 matches.	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 (classic) and on Mac is different from that in Outlook on the web, on mobile devices, and in new Outlook on Windows.
HTML item body	`getRegExMatches` returns any matches that are up to 3,072 (3 KB) characters, for a maximum of 50 matches.	`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 (classic) and on Mac is different from that in Outlook on the web, on mobile devices, and in new Outlook on Windows.

Jaa