Export (0) Print
Expand All
2 out of 2 rated this helpful - Rate this topic

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: April 01, 2014

Applies to: Exchange Online | Exchange Server 2013 | Exchange Server 2013 SP1 | Outlook 2013 | 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

Unless otherwise specified, references to "Outlook" apply to the Outlook rich client, 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. An end user or administrator 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.

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 data in a read form, and get or 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.

Mail apps that request this level of permission can do the following:

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. A mail app that has this level of permission can read all the properties of the current item in a read or compose form, get callback token and item attachments, write custom properties set by the app on that item, and use all the well-known entities or regular expressions in its activation rules. The following example follows schema v1.1. It shows a rule that activates the app 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>

Mail apps that use this level of permission can be activated in read and compose forms. Such mail apps can access only read methods (for example, Message.to in a read form and Message.to.get in a compose form). Such mail apps cannot access the following write methods and Mailbox.makeEWSRequestAsync:

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 can read and write all item-level properties of the item that is being viewed or composed in Outlook, and can add or remove attachments of that item. Mail apps with this permission can use all members of the JavaScript API for Office except Mailbox.makeEWSRequestAsync. Mail apps activated in compose forms and that use write methods (for example, Message.to.addAsync or Message.to.setAsync) must use at least this level of permission.

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. Mail apps can use all the well-known entities or regular expressions in their activation rules. Mail apps can read and write all properties of any item in the user’s mailbox, create, read, and write to any folder or item, and send an item from that mailbox. They do so by calling the Mailbox.makeEWSRequestAsync method which, in turn, calls the specified Exchange Web Service. The following Exchange Web Services operations are supported:

Attempting to use an unsupported operation will result in an error response.

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.