Understanding Outlook add-in permissions
Outlook add-ins specify the required permission level in their manifest. There are four available levels.
Permission level canonical name |
XML manifest name | unified manifest for Microsoft 365 name | Summary description |
---|---|---|---|
restricted | Restricted | MailboxItem.Restricted.User | Allows access to properties and methods that don't pertain to specific information about the user or mail item. |
read item | ReadItem | MailboxItem.Read.User | In addition to what is allowed in restricted, it allows:
|
read/write item | ReadWriteItem | MailboxItem.ReadWrite.User | In addition to what is allowed in read item, it allows:
|
read/write mailbox | ReadWriteMailbox | Mailbox.ReadWrite.User | In addition to what is allowed in read/write item, it allows:
|
Permissions are declared in the manifest. The markup varies depending on the type of manifest.
- XML 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 XML 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 XML manifest, specify the permission by setting the SupportsSharedFolders element to
true
. For details, see Enable 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.
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
Important
Entity-based contextual Outlook add-ins will be retired in Q2 of 2024. The work to retire this feature will start in May and continue until the end of June. After June, contextual add-ins will no longer be able to detect entities in mail items to perform tasks on them. The following APIs will also be retired.
- Office.context.mailbox.item.getEntities()
- Office.context.mailbox.item.getEntitiesByType(entityType)
- Office.context.mailbox.item.getFilteredEntitiesByName(name)
- Office.context.mailbox.item.getSelectedEntities()
To help minimize potential disruptions, the following will still be supported after entity-based contextual add-ins are retired.
- An alternative implementation of the Join button, which is activated by online meeting add-ins, is being developed. Once support for entity-based contextual add-ins ends, online meeting add-ins will automatically transition to the alternative implementation to activate the Join button. During the transition to this implementation, the Join button may not be visible when using an online meeting add-in. As a workaround, you must select the meeting link from the body of the meeting invitation to join the meeting directly.
- Regular expression rules will continue to be supported after entity-based contextual add-ins are retired. We recommend updating your contextual add-in to use regular expression rules as an alternative solution. For guidance on how to implement these rules, see Use regular expression activation rules to show an Outlook add-in.
For more information, see Retirement of entity-based contextual Outlook add-ins.
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.
Note
Outlook add-in features that depend on activation rules aren't supported when the add-in uses a Unified manifest for Microsoft 365.
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 entity.
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.addFileAttachmentAsync
- 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.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
read item 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.
Get a callback token to get item attachments or the full item with Exchange Web Services (EWS) or Outlook REST APIs.
Important
Legacy Exchange user identity tokens and callback tokens will be turned off for all Exchange Online tenants in October 2024 as 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. For more information, see our blog post about nested app authentication and legacy Exchange tokens.
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.
Important
Entity-based contextual Outlook add-ins will be retired in Q2 of 2024. The work to retire this feature will start in May and continue until the end of June. After June, contextual add-ins will no longer be able to detect entities in mail items to perform tasks on them. The following APIs will also be retired.
- Office.context.mailbox.item.getEntities()
- Office.context.mailbox.item.getEntitiesByType(entityType)
- Office.context.mailbox.item.getFilteredEntitiesByName(name)
- Office.context.mailbox.item.getSelectedEntities()
To help minimize potential disruptions, the following will still be supported after entity-based contextual add-ins are retired.
- An alternative implementation of the Join button, which is activated by online meeting add-ins, is being developed. Once support for entity-based contextual add-ins ends, online meeting add-ins will automatically transition to the alternative implementation to activate the Join button. During the transition to this implementation, the Join button may not be visible when using an online meeting add-in. As a workaround, you must select the meeting link from the body of the meeting invitation to join the meeting directly.
- Regular expression rules will continue to be supported after entity-based contextual add-ins are retired. We recommend updating your contextual add-in to use regular expression rules as an alternative solution. For guidance on how to implement these rules, see Use regular expression activation rules to show an Outlook add-in.
For more information, see Retirement of entity-based contextual Outlook add-ins.
Use all the well-known entities in ItemHasKnownEntity rules, or regular expressions in ItemHasRegularExpressionMatch rules.
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 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
read/write item permission
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.
Add or remove attachments of that item.
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 addition to what the read/write item 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.
Important
Legacy Exchange user identity tokens and callback tokens will be turned off for all Exchange Online tenants in October 2024 as 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. For more information, see our blog post about nested app authentication and legacy Exchange tokens.
See also
Office Add-ins
Tilbakemeldinger
https://aka.ms/ContentUserFeedback.
Kommer snart: Gjennom 2024 faser vi ut GitHub Issues som tilbakemeldingsmekanisme for innhold, og erstatter det med et nytt system for tilbakemeldinger. Hvis du vil ha mer informasjon, kan du se:Send inn og vis tilbakemelding for