Mail apps for Outlook

apps for Office

Create mail apps that extend Outlook in read or compose mode.

Last modified: June 16, 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 app?
Try some mail apps and see their code
Architecture components
Supported hosts
Mail apps documentation
Suggested tracks to learn more

A mail app 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 app. Mail apps 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 app once for a mailbox and it will work on the devices and Outlook clients that it is designed to.

Figure 1. Mail app running on a desktop, tablet, and smartphone

A mail app runs on desktop, tablet and smartphone

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

Read scenario

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

See the Bing Maps mail app 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 app for the message. The user sees a Bing Maps app button in the app bar. The user can select the app button to start the app. The mail app then displays a map of the address in the app pane. Figure 2 shows a message that contains a highlighted address in the Reading Pane of Outlook for Windows, the Bing Maps app button that has been chosen in the app bar, and the app displaying a map for the address in the app pane.

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

Figure 2. The app pane showing the Bing Maps mail app 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 apps for Office platform, in addition to read scenarios, mail apps can be activated when the user is composing a message or appointment as well. As an example, the My Templates mail app 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 apps for that message, including the My Templates mail app. The user chooses the Apps for Office button in the ribbon to open the app selection pane and see the activated mail apps, as shown in figure 3.

Figure 3. The app selection pane showing the My Templates mail app 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 app. The app 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 app pane on the right with the My Templates mail app started. The app lists a few templates that are ready for insertion in the message.

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

My Templates app activated for message in compose

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

YouTube mail app

See the YouTube mail app in Outlook.

Video

If you're interested in installing the YouTube mail app, follow the instructions in Install sample mail apps in Outlook to install it. See Sample: Create a mail app to view YouTube videos in Outlook for a description of the code.

To try the YouTube mail app, 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 app in the app bar. You can then choose the YouTube app button. In the app 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 app activated and selected for a message in the Reading Pane. The message contains a URL to a YouTube video.

Figure 5. YouTube mail app activated for a message in Outlook

YouTube mail app in Outlook

Phone dialer mail app

See the Phone Dialer mail app in Outlook.

Video

If you're interested in installing the phone dialer mail app, follow the instructions in Install sample mail apps in Outlook to install it. See Sample: Create a mail app for Voice Over IP dialing in Outlook for a description of the code.

To try the phone dialer mail app, 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 app in the app bar. You can then choose the Phone Dialer app button, and select a telephone number in the app pane to use VOIP to dial that number.

Note Note

This app uses Lync as the VOIP service to dial calls. To run this mail app, 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 app activated and selected for a message in the Reading Pane. The message contains a US phone number.

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

Phone dialer mail app in Outlook

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

  • An Exchange Server: the user’s mailbox and app 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 app source files (including HTML and JavaScript files) reside here. The mail app 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 app are designed to work seamlessly for the Outlook rich clients, Outlook Web App, and OWA for Devices. That is, a mail app 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.

Area

Articles

Code samples

Install sample mail apps in Outlook
Sample: Create a mail app to view YouTube videos in Outlook
Sample: Create a mail app for Voice Over IP dialing in Outlook
Sample: Debug properties of Outlook items
Sample: Create a mail app to display in Outlook hierarchy information from Active Directory

Start

Apps for Office platform overview
Create your first mail app for Outlook by using a text editor
Get started creating a mail app for Outlook with Napa Office 365 Development Tools
Create your first mail app for Outlook by using Visual Studio
Overview of mail apps for Outlook
Specify the APIs your mail app for Outlook requires
Update the manifest of a mail app from schema v1.0 to v1.1

Design

Design apps for Office

Learn

Develop apps for Office
Understanding the JavaScript API for Office
Referencing the JavaScript API for Office library from its content delivery network (CDN)
Loading the DOM and runtime environment
Asynchronous programming in apps for Office
Specify the Office hosts and APIs your app requires
Specify the Office hosts and APIs your app requires
Addressing same-origin policy limitations in apps for Office
Privacy and security for apps for Office
Localization for apps for Office
Create world-ready apps for Office and SharePoint
Overview of mail apps for Outlook
Create a manifest for a mail app to activate in a read or compose form in Outlook (schema v1.1)
Activate mail apps in Outlook clients
Activate a mail app in Outlook for a specific message class
Get and set Outlook item data in read or compose forms
Persist metadata for the same mailbox by using roaming settings
Save item-specific metadata as custom properties
Persist metadata for the same Outlook item in a mailbox using custom properties
Privacy, permissions, and security for mail apps in Outlook
Specify permissions for mail app access to the user's mailbox
Create mail apps for read forms in Outlook
Use regular expression activation rules to show a mail app in Outlook
Match strings in an Outlook item as well-known entities
Extract entity strings from an Outlook item
Get attachments of an Outlook item from an Exchange server
Create mail apps for compose forms in Outlook
Add and remove attachments to an item in a compose form in Outlook
Get and set item data in a compose form in Outlook
Create a mail app for Outlook that runs on desktops, tablets, and mobile devices (schema v1.1)
Call web services from a mail app for Outlook
Authenticate a mail app by using Exchange identity tokens
Deploy and install mail apps for testing in Outlook

How-to tasks

Specify the Office hosts and APIs your app requires

Navigate to more than one domain within the same app pane
Build a localized app for Office
Activate a mail app in Outlook for a specific message class
Extract entity strings from an Outlook item
Persist metadata for the same mailbox by using roaming settings
Persist metadata for the same Outlook item in a mailbox using custom properties
Get attachments of an Outlook item from an Exchange server
Add and remove attachments to an item in a compose form in Outlook
Get and set item data in a compose form in Outlook
Get, set, or add recipients when composing an appointment or message in Outlook
Get or set the subject when composing an appointment or message in Outlook
Insert data in the body when composing an appointment or message in Outlook
Get or set the location when composing an appointment in Outlook
Get or set the time when composing an appointment in Outlook

FAQ and best practices

FAQ for developing apps for Office
Best practices for developing apps for Office
Tips for handling date values in mail apps
Release notes (Office 2013 SP1, office.js v1.1, schema v1.1)

Troubleshooting

Compare mail app support in Outlook for Mac with other Outlook hosts
Limits for activation and JavaScript API for mail apps in Outlook
Troubleshoot mail apps activation
Sample: Debug properties of Outlook items
Diagnostics object
Following resource usage rules in apps for Office
Overriding resource usage settings for performance of apps for Office

Deploy, license, publish

Deploy and install mail apps for testing in Outlook
License your apps for Office and SharePoint
Publish Office and SharePoint Add-ins and Office 365 web apps

Reference

JavaScript API for Office

Schema reference for apps for Office manifests (v1.1)

See mail apps the first time in Outlook

Walk through simple mail apps

Upgrade from a previous release

Learn the basics

Sample code for common tasks

Best practices

Troubleshooting

Go deeper

Show:
© 2015 Microsoft