Limits for activation and JavaScript API for Outlook add-ins
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
getRegExMatchesmethod 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 expressionunder(?!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. |