Add support for add-in commands for Outlook Mobile
Using add-in commands in Outlook Mobile allows your users to access the same functionality (with some limitations) that they already have in Outlook on the web, Windows, and Mac. Adding support for Outlook Mobile requires updating the add-in manifest and possibly changing your code for mobile scenarios.
Updating the manifest
Note
Add-ins using the Unified Microsoft 365 manifest (preview) aren't currently supported on mobile devices.
The first step to enabling add-in commands in Outlook Mobile is to define them in the add-in manifest. The VersionOverrides v1.1 schema defines a new form factor for mobile, MobileFormFactor.
This element contains all of the information for loading the add-in in mobile clients. This enables you to define completely different UI elements and JavaScript files for the mobile experience.
The following example shows a single task pane button in a MobileFormFactor
element.
<VersionOverrides xmlns="http://schemas.microsoft.com/office/mailappversionoverrides/1.1" xsi:type="VersionOverridesV1_1">
...
<MobileFormFactor>
<FunctionFile resid="residUILessFunctionFileUrl" />
<ExtensionPoint xsi:type="MobileMessageReadCommandSurface">
<Group id="mobileMsgRead">
<Label resid="groupLabel" />
<Control xsi:type="MobileButton" id="TaskPaneBtn">
<Label resid="residTaskPaneButtonName" />
<Icon xsi:type="bt:MobileIconList">
<bt:Image size="25" scale="1" resid="tp0icon" />
<bt:Image size="25" scale="2" resid="tp0icon" />
<bt:Image size="25" scale="3" resid="tp0icon" />
<bt:Image size="32" scale="1" resid="tp0icon" />
<bt:Image size="32" scale="2" resid="tp0icon" />
<bt:Image size="32" scale="3" resid="tp0icon" />
<bt:Image size="48" scale="1" resid="tp0icon" />
<bt:Image size="48" scale="2" resid="tp0icon" />
<bt:Image size="48" scale="3" resid="tp0icon" />
</Icon>
<Action xsi:type="ShowTaskpane">
<SourceLocation resid="residTaskpaneUrl" />
</Action>
</Control>
</Group>
</ExtensionPoint>
</MobileFormFactor>
...
</VersionOverrides>
This is very similar to the elements that appear in a DesktopFormFactor element, with some notable differences.
- The OfficeTab element is not used.
- The ExtensionPoint element must have only one child element. If the add-in only adds one button, the child element should be a Control element. If the add-in adds more than one button, the child element should be a Group element that contains multiple
Control
elements. - There is no
Menu
type equivalent for theControl
element. - The Supertip element is not used.
- The required icon sizes are different. Mobile add-ins minimally must support 25x25, 32x32 and 48x48 pixel icons.
Code considerations
Designing an add-in for mobile introduces some additional considerations.
Use REST instead of Exchange Web Services
The Office.context.mailbox.makeEwsRequestAsync method is not supported in Outlook Mobile. Add-ins should prefer to get information from the Office.js API when possible. If add-ins require information not exposed by the Office.js API, then they should use the Outlook REST APIs to access the user's mailbox.
Mailbox requirement set 1.5 introduced a new version of Office.context.mailbox.getCallbackTokenAsync that can request an access token compatible with the REST APIs, and a new Office.context.mailbox.restUrl property that can be used to find the REST API endpoint for the user.
Pinch zoom
By default users can use the "pinch zoom" gesture to zoom in on task panes. If this does not make sense for your scenario, be sure to disable pinch zoom in your HTML.
Close task panes
In Outlook Mobile, task panes take up the entire screen and by default require the user to close them to return to the message. Consider using the Office.context.ui.closeContainer method to close the task pane when your scenario is complete.
Compose mode and appointments
Currently, add-ins in Outlook Mobile only support activation when reading messages. Add-ins are not activated when composing messages or when viewing or composing appointments. However, there are two exceptions:
- Online meeting provider integrated add-ins can be activated in Appointment Organizer mode. For more about this exception (including available APIs), refer to Create an Outlook mobile add-in for an online-meeting provider.
- Add-ins that log appointment notes and other details to customer relationship management (CRM) or note-taking services can be activated in Appointment Attendee mode. For more about this exception (including available APIs), refer to Log appointment notes to an external application in Outlook mobile add-ins.
Unsupported APIs
APIs introduced in requirement set 1.6 or later are not supported by Outlook Mobile. The following APIs from earlier requirement sets are also not supported.
- Office.context.officeTheme
- Office.context.mailbox.ewsUrl
- Office.context.mailbox.convertToEwsId
- Office.context.mailbox.convertToRestId
- Office.context.mailbox.displayAppointmentForm
- Office.context.mailbox.displayMessageForm
- Office.context.mailbox.displayNewAppointmentForm
- Office.context.mailbox.makeEwsRequestAsync
- Office.context.mailbox.item.dateTimeModified
- Office.context.mailbox.item.displayReplyAllForm
- Office.context.mailbox.item.displayReplyForm
- Office.context.mailbox.item.getEntities
- Office.context.mailbox.item.getEntitiesByType
- Office.context.mailbox.item.getFilteredEntitiesByName
- Office.context.mailbox.item.getRegexMatches
- Office.context.mailbox.item.getRegexMatchesByName
See also
Requirement sets supported by Exchange servers and Outlook clients
Feedback
Submit and view feedback for