Was this page helpful?
Your feedback about this content is important. Let us know what you think.
Additional feedback?
1500 characters remaining
Mail add-ins

Mail add-ins for Outlook

Office Add-ins

Create mail add-ins that extend Outlook in read or compose mode.

Last modified: August 31, 2015

Applies to: apps for Office | Office Add-ins | Outlook

Learn more about supported hosts and other requirements.

Note Note

The name "apps for Office" is changing to "Office Add-ins". During the transition, the documentation and the UI of some Office host applications and Visual Studio tools might still use the term "apps for Office". For details, see New name for apps for Office and SharePoint.

In this article
What is a mail add-in?
Try some mail add-ins and see their code
Architecture components
Supported hosts
Suggested tracks to learn more

A mail add-in is a webpage that is hosted inside Outlook. Outlook activates the webpage and makes it available to the user contextually with respect to the item that the user is currently viewing, creating, or replying to. The user controls starting any available mail add-in. Mail add-ins enhance the browsing or authoring experience. They can run seamlessly across the Outlook rich clients, Outlook Web App, and OWA for Devices. Users install a mail add-in once for a mailbox and it will work on the devices and Outlook clients that it is designed to.

Figure 1. Mail add-in running on a desktop, tablet, and smartphone

A mail app runs on desktop, tablet and smartphone

The Outlook items that support mail add-ins include email messages, meeting requests, responses and cancellations, and appointments. Each mail add-in defines the appropriate context for its activation - a context which occurs when the user is either reading or composing an item.

Read scenario

Mail add-ins can be activated when the user is viewing a message or appointment. As an example, the Bing Maps mail add-in can activate when the user is in a read form viewing a message that contains an address. The add-in enhances the browsing experience by conveniently providing a map of the address in the add-in pane, without requiring the user to leave Outlook.

See the Bing Maps mail add-in in Outlook.

Video

As seen in the preceding video, when the end user is viewing a message that contains an address in the Reading Pane (or inspector), Outlook activates the Bing Maps mail add-in for the message. The user sees a Bing Maps add-in button in the add-in bar. The user can select the add-in button to start the add-in. The mail add-in then displays a map of the address in the add-in pane. Figure 2 shows a message that contains a highlighted address in the Reading Pane of Outlook for Windows, the Bing Maps add-in button that has been chosen in the add-in bar, and the add-in displaying a map for the address in the add-in pane.

To close the add-in pane, the user can choose the add-in button again, move on to another message, or do something else in Outlook.

Figure 2. The add-in pane showing the Bing Maps mail add-in in action for the selected Outlook message that contains an address

Bing Map mail app in Outlook

Compose scenario

Starting in the second release of the Office Add-ins platform, in addition to read scenarios, mail add-ins can be activated when the user is composing a message or appointment as well. As an example, the My Templates mail add-in can activate in a message or appointment compose form and provide the convenience of inserting common responses. When the user is composing or replying to a message, Outlook activates the relevant mail add-ins for that message, including the My Templates mail add-in. The user chooses the Office Add-ins button in the ribbon to open the add-in selection pane and see the activated mail add-ins, as shown in figure 3.

Figure 3. The add-in selection pane showing the My Templates mail add-in activated for the message that is being composed

Templates mail app activated for composed item

The user then chooses the My Templates icon to start the add-in. The add-in pane on the right opens, and the user can conveniently insert commonly used text in the compose form. Figure 4 shows a message reply in a compose form and the add-in pane on the right with the My Templates mail add-in started. The add-in lists a few templates that are ready for insertion in the message.

Figure 4. The add-in pane showing the My Templates mail add-in in action for the message being composed

My Templates app activated for message in compose

The following are two other sample mail add-ins that activate when the user is viewing a message.

YouTube mail add-in

See the YouTube mail add-in in Outlook.

Video

To try the YouTube mail add-in, choose an email you have already received that has a URL to a YouTube video, or, create an email message, add one or more URLs to YouTube videos in the body, and send the message to yourself. When you display the message in the Reading Pane or an inspector, Outlook activates the add-in in the add-in bar. You can then choose the YouTube add-in button. In the add-in pane, choose a video thumbnail to select a video, or the YouTube embedded player to play a video.

The next figure shows the YouTube mail add-in activated and selected for a message in the Reading Pane. The message contains a URL to a YouTube video.

Figure 5. YouTube mail add-in activated for a message in Outlook

YouTube mail app in Outlook

Phone dialer mail add-in

See the Phone Dialer mail add-in in Outlook.

Video

To try the phone dialer mail add-in, create an email message, add one or more telephone numbers to the body and send it to yourself. When you display the message in the Reading Pane or in an inspector, Outlook activates the add-in in the add-in bar. You can then choose the Phone Dialer add-in button, and select a telephone number in the add-in pane to use VOIP to dial that number.

Note Note

This add-in uses Lync as the VOIP service to dial calls. To run this mail add-in, you must have access to Lync Server, and have installed the Lync client on the client computer and used it at least once to set it up. You can adapt the code to another VOIP service that supports the same callto: and tel: protocols.

The next figure shows the phone dialer mail add-in activated and selected for a message in the Reading Pane. The message contains a US phone number.

Figure 6. Phone dialer mail add-in activated for a message in Outlook

Phone dialer mail app in Outlook

The typical components involved in running a mail add-in include the following:

  • An Exchange Server: the user’s mailbox and add-in manifests reside here.

  • An Outlook client: the user views or composes a message or appointment in an Outlook rich client, Outlook Web App or OWA for Devices, on a desktop, tablet, or smartphone.

  • A web server: the mail add-in source files (including HTML and JavaScript files) reside here. The mail add-in can also access third-party web services on other web servers.

  • A CDN web server: the JavaScript API for Office library files reside on the Content Delivery Network (CDN) on this server.

Figure 7 shows how the typical components interact with one another when the user starts Outlook and views or composes a message or appointment.

Figure 7. Interaction of typical components when the user starts Outlook

Flow of events when starting Outlook mail app

The APIs to develop a mail add-in are designed to work seamlessly for the Outlook rich clients, Outlook Web App, and OWA for Devices. That is, a mail add-in calls the same JavaScript API when running on any of these hosts. Unless otherwise specified, references to "Outlook" apply to the Outlook rich clients that run on the desktop, Outlook Web App that runs in a browser on the desktop, tablets, and smartphones, and OWA for Devices that run as native clients on supporting tablets and smartphones.

See mail add-ins the first time in Outlook

Walk through simple mail add-ins

Upgrade from a previous release

Learn the basics

Sample code for common tasks

Best practices

Troubleshooting

Go deeper

Show:
© 2015 Microsoft