Create Outlook add-ins for read forms

Read add-ins activate in the Reading Pane or read inspector of Outlook. Unlike compose add-ins (Outlook add-ins that are activated when a user creates a message or appointment), read add-ins are available when users:

• View an email message, meeting request, meeting response, or meeting cancellation.

  Note

  Outlook doesn't activate add-ins in read form for certain types of messages, including items that are attachments to another message, items in the Outlook Drafts folder, or items that are encrypted or protected in other ways.

• View a meeting item in which the user is an attendee.

Locate a read add-in in Outlook

The location of an add-in in the Message Read surface depends on your Outlook client.

• Windows, Mac: Select the add-in from the ribbon of the Reading Pane or read inspector.

  

• Web, new Outlook on Windows (preview): Select or open a message in a new window, then select the add-in from the message action bar. If your add-in doesn't appear in the action bar, select Apps to view your installed add-ins.

  

To select an add-in from the Appointment Read surface, open a meeting, then select the add-in from the ribbon.

Types of add-ins available in read mode

Read add-ins can be any combination of the following types.

• Add-in commands

• Contextual Outlook add-ins

  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 Meeting 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 Meeting button.
  • 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.

See also

• Build your first Outlook add-in
• Outlook add-in APIs