Permissions are declared in the manifest. The markup varies depending on the type of manifest.
Add-in only manifest: Use the <Permissions> element.
Unified manifest for Microsoft 365: Use the "name" property of an object in the "authorization.permissions.resourceSpecific" array.
Note
There's a supplementary permission needed for add-ins that use the append-on-send feature. With the add-in only manifest, specify the permission in the ExtendedPermissions element. For details, see Implement append-on-send in your Outlook add-in. With the unified manifest, specify this permission with the name Mailbox.AppendOnSend.User in an additional object in the "authorization.permissions.resourceSpecific" array.
There's a supplementary permission needed for add-ins that use shared folders. With the add-in only manifest, specify the permission by setting the SupportsSharedFolders element to true. For details, see Implement shared folders and shared mailbox scenarios in an Outlook add-in. With the unified manifest, specify this permission with the name Mailbox.SharedFolder in an additional object in the "authorization.permissions.resourceSpecific" array.
The four levels of permissions are cumulative: the read/write mailbox permission includes the permissions of read/write item, read item and restricted, read/write item includes read item and restricted, and the read item permission includes restricted.
You can see the permissions requested by a mail add-in before installing it from AppSource. You can also see the required permissions of installed add-ins in the Exchange Admin Center.
Tip
To make sure that your Outlook add-in specifies the correct permission level, verify the minimum permission level required by each API implemented by your add-in. For information on minimum permission levels, see Outlook API reference.
restricted permission
The restricted permission is the most basic level of permission. Outlook assigns this permission to a mail add-in by default if the add-in doesn't request a specific permission in its manifest.
Can do
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).
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.
The read item permission is the next level of permission in the permissions model.
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.
In Exchange on-premises environments, get a callback token to get the full mail item with Exchange Web Services (EWS).
Important
Legacy Exchange tokens are deprecated. Starting February 2025, we'll begin to turn off legacy Exchange user identity and callback tokens for Exchange Online tenants. For the timeline and details, see our FAQ page. This is part of Microsoft's Secure Future Initiative, which gives organizations the tools needed to respond to the current threat landscape. Exchange user identity tokens will still work for Exchange on-premises. Nested app authentication is the recommended approach for tokens going forward.
Specify read/write item permission 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.
Use all other members of the Office JavaScript API 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.
Get the current calendar event item using the Outlook REST API.
Use mailbox.makeEWSRequestAsync.
read/write mailbox permission
The read/write mailbox permission is the highest level of permission.
In Exchange on-premises environments, 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.
Attempting to use an unsupported operation will result in an error response.
Important
Legacy Exchange tokens are deprecated. Starting February 2025, we'll begin to turn off legacy Exchange user identity and callback tokens for Exchange Online tenants. For the timeline and details, see our FAQ page. This is part of Microsoft's Secure Future Initiative, which gives organizations the tools needed to respond to the current threat landscape. Exchange user identity tokens will still work for Exchange on-premises. Nested app authentication is the recommended approach for tokens going forward.
The source for this content can be found on GitHub, where you can also create and review issues and pull requests. For more information, see our contributor guide.
Office Add-ins feedback
Office Add-ins is an open source project. Select a link to provide feedback: