Outlook add-ins specify the required permission level in their manifest. The available levels are Restricted, ReadItem, ReadWriteItem, or ReadWriteMailbox. These levels of permissions are cumulative: Restricted is the lowest level, and each higher level includes the permissions of all the lower levels. ReadWriteMailbox includes all the supported permissions.
You can see the permissions requested by a mail add-in before installing it from the Office Store. You can also see the required permissions of installed add-ins in the Exchange Admin Center.
Restricted permission
The Restricted permission is the most basic level of permission. Specify Restricted in the Permissions element in the manifest to request this permission. Outlook assigns this permission to a mail add-in by default if the add-in does not request a specific permission in its manifest.
Can do
- Get only specific entities (phone number, address, URL) from the item's subject or body.
- Specify an ItemIs activation rule that requires the current item in a read or compose form to be a specific item type, or ItemHasKnownEntity rule that matches any of a smaller subset of supported well-known entities (phone number, address, URL) in the selected item.
- Access any properties and methods that do not pertain to specific information about the user or item. (See the next section for the list of members that do.)
Can't do
- Use an ItemHasKnownEntity rule on the contact, email address, meeting suggestion, or task suggestion entitiy.
- Use the ItemHasAttachment or ItemHasRegularExpressionMatch rule.
Access the members in the following list that pertain to the information of the user or item. Attempting to access members in this list will return null and result in an error message which states that Outlook requires the mail add-in to have elevated permission.
- item.addItemAttachmentAsync
- item.attachments
- item.bcc
- item.body
- item.cc
- item.from
- item.getRegExMatches
- item.getRegExMatchesByName
- item.optionalAttendees
- item.organizer
- item.removeAttachmentAsync
- item.requiredAttendees
- item.resources
- item.sender
- item.to
- mailbox.getCallbackTokenAsync
- mailbox.getUserIdentityTokenAsync
- mailbox.makeEwsRequestAsync
- mailbox.userProfile
- Body and all its child members
- Location and all its child members
- Recipients and all its child members
- Subject and all its child members
- Time and all its child members
ReadItem permission
The ReadItem permission is the next level of permission in the permissions model. Specify ReadItem in the Permissions element in the manifest to request this permission.
Can do
- Read all the properties of the current item in a read or compose form, for example, item.to in a read form and item.to.getAsync in a compose form.
- Get a callback token to get item attachments or the full item with Exchange Web Services (EWS) or Outlook REST APIs.
- Write custom properties set by the add-in on that item.
- Get all existing well-known entities, not just a subset, from the item's subject or body.
- Use all the well-known entities in ItemHasKnownEntity rules, or regular expressions in ItemHasRegularExpressionMatch rules. The following example follows schema v1.1. It shows a rule that activates the add-in if one or more of the well-known entities are found in the subject or body of the selected message:
<Permissions>ReadItem</Permissions>
<Rule xsi:type="RuleCollection" Mode="And">
<Rule xsi:type="ItemIs" FormType = "Read" ItemType="Message" />
<Rule xsi:type="RuleCollection" Mode="Or">
<Rule xsi:type="ItemHasKnownEntity"
EntityType="PhoneNumber" />
<Rule xsi:type="ItemHasKnownEntity" EntityType="Address" />
<Rule xsi:type="ItemHasKnownEntity" EntityType="Url" />
<Rule xsi:type="ItemHasKnownEntity"
EntityType="MeetingSuggestion" />
<Rule xsi:type="ItemHasKnownEntity"
EntityType="TaskSuggestion" />
<Rule xsi:type="ItemHasKnownEntity"
EntityType="EmailAddress" />
<Rule xsi:type="ItemHasKnownEntity" EntityType="Contact" />
</Rule>
Can't do
- Use the token provided by mailbox.getCallbackTokenAsync to update or delete the current item using the Outlook REST API or access any other items in the user's mailbox.
- Use any of the following APIs:
- mailbox.makeEwsRequestAsync
- item.addFileAttachmentAsync
- item.addItemAttachmentAsync
- item.bcc.addAsync
- item.bcc.setAsync
- item.body.prependAsync
- item.body.setAsync
- item.body.setSelectedDataAsync
- item.cc.addAsync
- item.cc.setAsync
- item.end.setAsync
- item.location.setAsync
- item.optionalAttendees.addAsync
- item.optionalAttendees.setAsync
- item.removeAttachmentAsync
- item.requiredAttendees.addAsync
- item.requiredAttendees.setAsync
- item.start.setAsync
- item.subject.setAsync
- item.to.addAsync
- item.to.setAsync
ReadWriteItem permission
Specify ReadWriteItem in the Permissions element in the manifest to request this permission. Mail add-ins activated in compose forms that use write methods ( Message.to.addAsync or Message.to.setAsync) must use at least this level of permission.
Can do
- Read and write all item-level properties of the item that is being viewed or composed in Outlook.
- Add or remove attachments of that item.
- Use all other members of the JavaScript API for Office that are applicable to mail add-ins, except Mailbox.makeEWSRequestAsync.
Can't do
- Use the token provided by mailbox.getCallbackTokenAsync to update or delete the current item using the Outlook REST API or access any other items in the user's mailbox.
- Use mailbox.makeEWSRequestAsync.
ReadWriteMailbox permission
The ReadWriteMailbox permission is the highest level of permission. Specify ReadWriteMailbox in the Permissions element in the manifest to request this permission.
In addition to what the ReadWriteItem permission supports, the token provided by mailbox.getCallbackTokenAsync provides access to use Exchange Web Services (EWS) operations or Outlook REST APIs to do the following:
- Read and write all properties of any item in the user's mailbox.
- Create, read, and write to any folder or item in that mailbox.
- Send an item from that mailbox
Through mailbox.makeEWSRequestAsync, you can access the following EWS operations:
- CopyItem
- CreateFolder
- CreateItem
- FindConversation
- FindFolder
- FindItem
- GetConversationItems
- GetFolder
- GetItem
- MarkAsJunk
- MoveItem
- SendItem
- UpdateFolder
- UpdateItem
Attempting to use an unsupported operation will result in an error response.
