Add-in commands for Outlook
Outlook add-in commands provide ways to initiate specific add-in actions from the ribbon by adding buttons or drop-down menus. This lets users access add-ins in a simple, intuitive, and unobtrusive way. Because they offer increased functionality in a seamless manner, you can use add-in commands to create more engaging solutions.
Add-in commands are available only in Outlook 2013 or later on Windows, Outlook 2016 or later on Mac, Outlook on iPhone, Outlook on Android, Outlook on the web for Exchange 2016 or later, and Outlook on the web for Office 365 and Outlook.com.
Support for add-in commands in Outlook 2013 requires three updates:
- March 8, 2016 security update for Outlook
- March 8, 2016 security update for Office (KB3114816)
- March 8, 2016 security update for Office (KB3114828)
Support for add-in commands in Exchange 2016 requires Cumulative Update 5.
Add-in commands are only available for add-ins that do not use ItemHasAttachment, ItemHasKnownEntity, or ItemHasRegularExpressionMatch rules to limit the types of items they activate on. However, contextual add-ins can present different commands depending on whether the currently selected item is a message or appointment, and can choose to appear in read or compose scenarios. Using add-in commands if possible is a best practice.
Creating the add-in command
Add-in commands are declared in the add-in manifest in the VersionOverrides element. This element is an addition to the manifest schema v1.1 that ensures backward compatibility. In a client that doesn't support
VersionOverrides, existing add-ins will continue to function as they did without add-in commands.
VersionOverrides manifest entries specify many things for the add-in, such as the host, types of controls to add to the ribbon, the text, the icons, and any associated functions.
When an add-in needs to provide status updates, such as progress indicators or error messages, it must do so through the notification APIs. The processing for the notifications must also be defined in a separate HTML file that is specified in the
FunctionFile node of the manifest.
Developers should define icons for all required sizes so that the add-in commands will adjust smoothly along with the ribbon. The required icon sizes are 80 x 80 pixels, 32 x 32 pixels, and 16 x 16 pixels for desktop, and 48 x 48 pixels, 32 x 32 pixels, and 25 x 25 pixels for mobile.
For more information about creating add-in commands, see Create add-in commands in your manifest.
How do add-in commands appear?
An add-in command appears on the ribbon as a button. When a user installs an add-in, its commands appear in the UI as a group of buttons. This can either be on the ribbon's default tab or on a custom tab. For messages, the default is either the Home or Message tab. For the calendar, the default is the Meeting, Meeting Occurrence, Meeting Series, or Appointment tab. For module extensions, the default is a custom tab. On the default tab, each add-in can have one ribbon group with up to 6 commands. On custom tabs, the add-in can have up to 10 groups, each with 6 commands. Add-ins are limited to only one custom tab.
As the ribbon gets more crowded, add-in commands will be displayed in the overflow menu. The add-in commands for an add-in are usually grouped together.
When an add-in command is added to an add-in, the add-in name is removed from the app bar. Only the add-in command button on the ribbon remains.
Modern Outlook on the web
In Outlook on the web, the add-in name is displayed in an overflow menu. If the add-in has multiple add-in commands, you can expand the add-in menu to see the group of buttons labeled with the add-in name.
What UX shapes exist for add-in commands?
The UX shape for an add-in command consists of a ribbon tab in the host application that contains buttons that can perform various functions. Currently, three UI shapes are supported:
- A button that launches a task pane
- A button that shows a drop-down menu with one or more buttons of the other two types
Launching a task pane
Use an add-in command button to launch a task pane for scenarios where a user needs to interact with an add-in for a longer period of time. For example, the add-in requires changes to settings or the completion of many fields.
The default width of the vertical task pane is 320 px. The vertical task pane can be resized in both the Outlook Explorer and inspector. The pane can be resized in the same way the to-do pane and list view resize.
This screenshot shows an example of a vertical task pane. The pane opens with the name of the add-in command in the top left corner. Users can use the X button in the upper-right corner of the pane to close the add-in when they are finished using it. By default, this pane will not persist across messages. Add-ins can support pinning for the task pane and receive events when a new message is selected. All UI elements rendered in the task pane, aside from the add-in name and the close button, are provided by the add-in.
If a user chooses another add-in command that opens a task pane, the task pane is replaced with the recently used command. If a user chooses an add-in command button that executes a function, or drop-down menu while the task pane is open, the action will be completed and the task pane will remain open.
A drop-down menu add-in command defines a static list of buttons. The buttons within the menu can be any mix of buttons that execute a function or buttons that open a task pane. Submenus are not supported.
Where do add-in commands appear in the UI?
Add-in commands are supported for four scenarios:
Reading a message
When the user is reading a message in the reading pane or in the Message tab for a pop-out read form, add-in commands added to the default tab appear on the Home tab.
Composing a message
When the user is composing a message, add-in commands added to the default tab appear on the Message tab.
Creating or viewing an appointment or meeting as the organizer
When creating or viewing an appointment or meeting as the organizer, add-in commands added to the default tab appear on the Meeting, Meeting Occurrence, Meeting Series, or Appointment tabs on pop-out forms. However, if the user selects an item in the calendar but doesn't open the pop-out, the add-in's ribbon group won't be visible in the ribbon.
Viewing a meeting as an attendee
When viewing a meeting as an attendee, add-in commands added to the default tab appear on the Meeting, Meeting Occurrence, or Meeting Series tabs on pop-out forms. However, if a user selects an item in the calendar but doesn't open the pop-out, the add-in's ribbon group won't be visible in the ribbon
Using a module extension
When using a module extension, add-in commands appear on the extension's custom tab.