Limits for activation and JavaScript API for Outlook add-ins

  • Articolo

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.

See also