Specify permissions for mail app access to the user's mailbox

apps for Office

Learn about each tier of the permissions model to request the necessary mailbox access for a mail app: Restricted, ReadItem, ReadWriteItem or ReadWriteMailbox.

Last modified: May 16, 2014

Applies to: Exchange Online | Exchange Server 2013 | Exchange Server 2013 SP1 | Outlook 2013 | Outlook 2013 RT | Outlook 2013 SP1 | Outlook Web App | OWA for Devices

   Office.js: v1.0, v1.1

   Apps for Office manifests schema: v1.0, v1.1

Note Note

"Outlook" in this article refers to the Outlook rich client, Outlook RT, Outlook Web App, and OWA for Devices.

In this article
Permissions model
Restricted permission
Read item permission
Read/write item permission
Read/write mailbox permission
Additional resources

A developer specifies Restricted, ReadItem, ReadWriteItem or ReadWriteMailbox in the manifest of a mail app to request the corresponding restricted, read item, read/write item or read/write mailbox permission to access the user's mailbox. These levels of permissions are cumulative: restricted is the lowest level, each higher level includes the permissions of all the lower levels plus some extra permissions, and read/write mailbox is the highest level that includes all the supported permissions.

You can see the permissions requested by a mail app before installing it from the Office Store. Only administrators can install mail apps that require the read/write mailbox permission. You can also see the required permissions of installed apps in the Exchange Admin Center.

Note Note

In version 1.0 of the apps for Office manifests schema, mail apps can be activated only when the user is viewing a message or appointment item. There were 3 tiers of permissions: restricted, read item, and read/write mailbox. Starting in version 1.1 of the schema, mail apps can be activated when the user is authoring an item in a compose form as well. There are 4 tiers of permissions: restricted, read item, read/write item or read/write mailbox. The appropriate permissions would allow mail apps to get certain data in a read or compose form, and set data in a compose form.

The restricted permission is the most basic level of permission. Developers can specify Restricted in the Permissions element in the manifest to request this permission. Outlook assigns this permission to a mail app by default if the app 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

The read item permission is the next level of permission in the permissions model. Developers can specify ReadItem in the Permissions element in the manifest to request this permission.

Can do

    <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" />

Can't do

If you are using the apps for Office manifest schema version 1.1 or later: The next level of permission is read/write item. Developers can specify ReadWriteItem in the Permissions element in the manifest to request this permission. Mail apps activated in compose forms and use write methods (for example, Message.to.addAsync or Message.to.setAsync) must use at least this level of permission.

Can do

Can't do

Use Mailbox.makeEWSRequestAsync.

The read/write mailbox permission is the highest level of permission in the permissions model. Developers can specify ReadWriteMailbox in the Permissions element in the manifest to request this permission.

In addition to what the read/write item permission supports, by using Mailbox.makeEWSRequestAsync, you can access supported Exchange Web Services (EWS) operations 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.

© 2014 Microsoft