Export (0) Print
Expand All

Mail apps for Outlook

apps for Office

See a mail app from the end-user's perspective, and watch videos of sample mail apps, including Bing Map, YouTube, and Phone dialer. Learn the course of events that takes place beginning with Outlook starting up and the user selecting or authoring an item, and how a mail app interacts with the user, Outlook, an Exchange server, and web servers. Follow up with more technical topics that will help you get on your way to creating mail apps for Outlook, Outlook Web App and OWA for Devices.

Last modified: May 23, 2014

Applies to: Exchange Online | Exchange Server 2013 | Exchange Server 2013 SP1 | Outlook 2013 | Outlook 2013 RT | Outlook 2013 SP1 | Outlook Web App | OWA for Devices

   Office.js: v1.0, v1.1

   Apps for Office manifests schema: v1.0, v1.1

Note Note

"Outlook" in this article refers to the Outlook rich client, Outlook RT, Outlook Web App, and OWA for Devices.

A mail app is a webpage that is hosted inside Outlook. Outlook activates it 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 client, Outlook Web App and OWA for Devices, such that you need to install a mail app only once for a mailbox and it will work on the devices and Outlook clients that it is designed to.

Figure 1. The same mail app can run 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 in the Reading Pane that contains a highlighted address, the Bing Maps app button 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 How to: 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 How to: 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 the 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 client, Outlook Web App and OWA for Devices. That is, a mail app calls the same JavaScript API when running on any of these hosts. Therefore, in general, unless otherwise specified in this documentation, references to "Outlook" apply broadly to the Outlook rich client that runs 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.

There are a few topics in which requirements or behavior differs among these client programs. For example, Set up a mail app for Outlook on tablets and mobile devices (schema v1.1). Such topics would specifically call out the "Outlook rich client", "Outlook Web App", "OWA for Devices" or specific members of the OWA for Devices collection.

The following is a complete list of documentation about developing mail apps for Outlook.

Area

Related documentation

Code samples

How to: 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

Overview of apps for Office
How to: Create your first mail app for Outlook by using a text editor
How to: Create your first mail app for Outlook by using "Napa" Office 365 Development Tools
How to: Create your first mail app for Outlook by using Visual Studio
What's new for mail apps in Office 2013 SP1
Start with fundamental concepts for mail apps in Outlook
Choosing a version of the platform for your mail app for Outlook
Mail app features per version
Updating the manifest of a mail app from schema v1.0 to v1.1

Design

Apps for Office UX design guidelines

Learn

Development lifecycle for 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
How to: Specify API requirement sets and methods for your app (manifest schema v1.1)
How to: Specify the Office host applications your app supports (manifest schema v1.1)
How to: Specify the Office host applications your app supports (manifest schema v1.0)
Addressing same-origin policy limitations in apps for Office
Privacy and security for apps for Office
Designing an app for Office for specific locales
World-ready apps for Office and SharePoint
Start with fundamental concepts for mail apps in Outlook
Creating a manifest for a mail app to activate in a read or compose form in Outlook (schema v1.1)
Creating a manifest for a mail app to activate in a read form in Outlook (schema v1.0)
Activate mail apps in Outlook clients
How to: Activate a mail app in Outlook for a specific message class
Get and set Outlook item data in read or compose forms
How to: Persist metadata for the same mailbox by using roaming settings
Save item-specific metadata as custom properties
How to: 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
Sample: Extract entity strings from an Outlook item
How to: 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
Set up a mail app for Outlook on tablets and mobile devices (schema v1.1)
Set up a mail app for Outlook on tablets and mobile devices (schema v1.0)
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

How to: Specify the Office host applications your app supports (manifest schema v1.1)
How to: Specify the Office host applications your app supports (manifest schema v1.0)
How to: Navigate to more than one domain within the same app pane
How to: Build a localized app for Office
How to: Activate a mail app in Outlook for a specific message class
Sample: Extract entity strings from an Outlook item
How to: Persist metadata for the same mailbox by using roaming settings
How to: Persist metadata for the same Outlook item in a mailbox using custom properties
How to: 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
How to: Get, set, or add recipients when composing an appointment or message in Outlook
How to: Get or set the subject when composing an appointment or message in Outlook
How to: Insert data in the body when composing an appointment or message in Outlook
How to: Get or set the location when composing an appointment in Outlook
How to: 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 for apps for Office (Office 2013 SP1, office.js v1.1, schema v1.1)

Troubleshooting

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
Licensing apps for Office and SharePoint
Publish apps for Office and SharePoint to the Microsoft Seller Dashboard

Reference

JavaScript API for Office (v1.1)
JavaScript API for Office (v1.0)
Schema reference for apps for Office manifests (v1.1)
Schema reference for apps for Office manifests (v1.0)

Depending on your purposes, the following tracks suggest topics to help you get on your way.

Seeing mail apps the first time in Outlook

The following topics answer the basic question "What is a mail app?" from both the end user and developer perspectives. They point you to videos of sample mail apps running in Outlook, and also explain the sample code.

Stepping through simple mail apps

Upgrading from a previous release

Learning the basics

The following topics cover fundamental information for developing apps for Office in general:

The following topics cover fundamental information for developing mail apps:

Sample code for common tasks

FAQ, best practices, known issues

Depending on the development tool you use, web development can entail behavior that is difficult to track. The following topics suggest issues that you should be aware of.

Troubleshooting

Ready for more breadth and depth

Show:
© 2014 Microsoft