Export (0) Print
Expand All

How to: Create your first mail app for Outlook by using Visual Studio

apps for Office

Learn how to develop and test a mail app for Outlook by using Visual Studio. This topic shows you how to create a simple mail app that shows a table. The table contains the email address of the sender and the first recipient found in an email message. This walkthrough also shows you how to display some basic information from the web by using the sender name of the mail.

To view a more detailed end-to-end example, see Basic concepts for using Visual Studio to develop and debug apps for Office.

After you have created your first mail app using Visual Studio, learn more about mail apps, and the fundamentals for developing mail apps in Outlook.

Last modified: May 30, 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

We can also show you how to create a mail app directly out of browser window or by using a text editor. If you’re not quite sure which tool to use, read Development basics.

In this article
Prerequisites for creating your first mail app
Create a project for the app
Provide a name and description for your mail app
Develop the content for your mail app
Show information from web sites and services
Test the mail app
Next steps
Additional resources

You need the following components to complete this walkthrough:

  • Microsoft Visual Studio 2013 and the Microsoft Office Developer Tools for Visual Studio 2013 (March 2014 update).

    -or-

    Visual Studio 2012 and the Microsoft Office Developer Tools for Visual Studio 2012. You can download the Microsoft Office Developer Tools for Visual Studio 2012 from the Office Dev Center.

  • Outlook 2013.

To get started, create an app project in Visual Studio.

To create an app project in Visual Studio

  1. Start Visual Studio.

  2. On the menu bar, choose File, New Project.

    The New Project dialog box opens.

  3. In the templates pane, under the node for the language you want to use, expand Office/SharePoint.

  4. In the list of project types for Apps, choose Apps for Office.

  5. Name the project MyFirstMailApp, and then choose the OK button.

    The Create app for Office dialog box opens.

  6. If you're using Visual Studio 2013:

    1. In the Create app for Office dialog box, choose the Mail option, and then choose the Next button.

    2. In the Choose where you want the app to appear page, clear all of the check boxes except for the Read form check box under the Email message section, and then choose the Finish button.

    In this example, we'll focus on creating an app that reads an email message.

  7. If you're using Visual Studio 2012:

    1. In the Create app for Office dialog box, choose the Mail app in: option.

    2. Clear the Appointment check box, and then choose the Finish button.

    When you complete the wizard, Visual Studio creates a solution. The solution contains a mail app project and an ASP.NET web application project:

    • The mail app project contains only an XML manifest file. Visual Studio generates the contents of this file for you. Therefore, you can run the project and see your mail app adjacent to Outlook items immediately.

    • The ASP.NET web application project contains the content pages of your mail app. It contains all of the files and file references that you need to develop Outlook-aware HTML and JavaScript pages. While you develop your mail app, Visual Studio hosts the web application project on your local IIS server.

You can specify a name to appear in the label of the app button when Outlook activates the mail app. You can also provide a description to help users who want to install your mail app understand what your app does.

You can update the name and description in the manifest editor. You can also provide values for other common settings related to your mail app. To modify more advanced settings, you can edit the XML manifest file directly.

In this procedure, you'll provide a name and description by using the manifest editor. Then, you'll modify the description in the XML manifest file to see how the information in the XML manifest file stays in sync with the information in the manifest editor.

To provide a name and description for your mail app

  1. In Solution Explorer, expand the mail app project node, and choose the MyFirstMailAppManifest folder

  2. On the View menu, choose Open.

    The manifest editor opens and several fields appear in the editor.

  3. In the Display name field, enter My First Mail App.

  4. In the Description field, enter This is my first mail app.

  5. Save the project and then close the manifest.

  6. In Solution Explorer, expand the MyFirstMailAppManifest folder, and then choose the MyFirstMailApp.xml file.

    Note Note

    This is the underlying XML file for the app manifest that is viewed in the manifest editor.

  7. On the View menu, choose Open.

    The XML manifest file of the project opens in the code editor.

    The XML manifest file describes how your mail app should be activated when an end user installs and uses it. The DefaultValue attribute of the DisplayName element contains the name that you provided in the manifest editor. The DefaultValue attribute of the Description element contains the description that you provided in the manifest editor.

  8. In the XML manifest file, set the DefaultValue attribute of the Description element to I modified this description by editing the XML manifest file directly.

  9. In Solution Explorer, choose the MyFirstMailAppManifest folder.

  10. On the View menu, choose Open.

    The manifest editor opens again. The description that appears in the Description field now contains the string "I modified this description by editing the XML manifest file directly". The editor and the XML file remain in sync.

Although the mail app project publishes the settings that describe your mail app, the web application provides the content that appears in the mail app.

The web application project contains a default HTML page and JavaScript file that you can use to get started. These files are convenient because they contain all the file references that you need to get started quickly.

In this procedure, you'll add HTML to the default.html page that shows a table. Then, you'll populate the contents of the table by adding code to the default JavaScript file. The code calls into the JavaScript API for Office.

To develop the web application in Visual Studio 2013

  1. In Solution Explorer, expand the MyFirstMailAppWeb project folder, expand the AppRead folder, expand the Home folder, and then choose the Home.html file.

    The default HTML file opens in the code editor.

  2. In the HTML file, replace the opening and closing <body> tags with the following HTML code. This code defines the table that will show the first recipient found in the current email message.

    <body style="margin: 4px">
        <h3>Email Details</h3>
        <table>
           <tr><td>&nbsp;</td><td>Sender</td><td>Recipient</td></tr>
           <tr><td>Display Name</td><td id="senderDisplayName" /><td id="recipientDisplayName" /></tr>
           <tr><td>Email Address</td><td id="senderEmailAddress" /><td id="recipientEmailAddress" /></tr>
        </table> 
    </body>
    
  3. In Solution Explorer, (still in the AppCompose, Home folder), choose the Home.js file.

  4. At the top of the JavaScript file, declare variables to represent Outlook and store the mailbox and settings objects.

    var outlook;
    var mailbox;
    var settings;
    
  5. Replace the Office.Initialize function with the following code. This code creates a table that contains the sender and recipient of the email message.

        // The Office initialize function must be run each time a new page is loaded
        Office.initialize = function (reason) {
            $(document).ready(function () {
                app.initialize();
    
                mailbox = Office.context.mailbox
                settings = Office.context.roamingSettings;
    
                $('#senderDisplayName').text(mailbox.item.sender.displayName);
                $('#senderEmailAddress').text(mailbox.item.sender.emailAddress);
                $('#recipientDisplayName').text(mailbox.item.to[0].displayName);
                $('#recipientEmailAddress').text(mailbox.item.to[0].emailAddress);
            });
        };
    

To develop the web application in Visual Studio 2012

  1. In Solution Explorer, expand the MyFirstMailAppWeb project folder, expand the App folder, expand the Home folder, and then choose the Home.html file.

  2. On the View menu, choose Code.

    The default HTML file opens in the code editor.

  3. In the HTML file, replace the opening and closing <body> tags with the following HTML code. This code defines the table that will show the first recipient found in the current email message.

    <body style="margin: 4px">
        <h3>Email Details</h3>
        <table>
           <tr><td>&nbsp;</td><td>Sender</td><td>Recipient</td></tr>
           <tr><td>Display Name</td><td id="senderDisplayName" /><td id="recipientDisplayName" /></tr>
           <tr><td>Email Address</td><td id="senderEmailAddress" /><td id="recipientEmailAddress" /></tr>
        </table> 
    </body>
    
    
  4. In Solution Explorer, (still in the AppCompose, Home folder), choose the Home.js file.

  5. On the View menu, choose Open.

  6. At the top of the JavaScript file, declare variables to represent Outlook and store the mailbox and settings objects.

    var outlook;
    var mailbox;
    var settings;
    
  7. Replace the Office.Initialize function with the following code. This code creates a table that contains the sender and recipient of the email message.

        // The Office initialize function must be run each time a new page is loaded
        Office.initialize = function (reason) {
            $(document).ready(function () {
                app.initialize();
    
                mailbox = Office.context.mailbox
                settings = Office.context.roamingSettings;
    
                $('#senderDisplayName').text(mailbox.item.sender.displayName);
                $('#senderEmailAddress').text(mailbox.item.sender.emailAddress);
                $('#recipientDisplayName').text(mailbox.item.to[0].displayName);
                $('#recipientEmailAddress').text(mailbox.item.to[0].emailAddress);
            });
        };
    
    
    

This topic shows you how to get names and addresses from the mail message. However, you can also get other information such as addresses, contacts, and phone numbers that appear in the subject and body of a mail message.

You may want to do more than just show that information in the mail app. For example, you might want to show a history of property values that relate to an address that appears in a mail. In fact, the topic How to: Create your first mail app for Outlook by using "Napa" Office 365 Development Tools shows you an example of doing that very thing. In most cases, you’ll want to consume data by using the API of various service providers. That option gives you the most flexibility in handling the data, but in most cases requires you to obtain an access key. Sometimes service providers expose widgets or plugins that you can use to show data in your page without requiring you to obtain an access key.

You can also just open a web page and pass data that you get from the mail item as parameters. For the purpose of this walkthrough, that’s the simplest option.

Note Note

Because many web page publishers won’t allow a web page to appear in an <iframe> (for security reasons), this option replaces the entire app with the target page. If you want users to perform other actions in the app besides view information from another site, consider using services, widgets, and plugins instead.

To open a page and use information from the mail item as parameters

  1. In the Home.html file, add the following HTML after the closing </table> element.

    <input id="searchLinkedIn" type="button" />
    
  2. In the Home.js file, add the following code to the $(document).ready function.

    $('#searchLinkedIn').val('search LinkedIn for ' + mailbox.item.sender.displayName);
                $('#searchLinkedIn').click(searchLinkedIn);
    
  3. At the bottom of the Home.js file, add the following function. This function searches the LinkedIn web site for the sender name and displays the results.

    function searchLinkedIn() {
        var from = Office.context.mailbox.item.sender.displayName;
        var split = from.split(' ');
        var firstName = '';
        var lastName = '';
    
        // Assumes first string in name is first name.
        firstName = split[0];
    
        if (split.length > 0){
            lastName = split[split.length - 1];
        }
        var src = "https://www.linkedin.com/pub/dir/?first=" + firstName + "&last=" + lastName + "&search=Search";
        window.location.href(src);
            
    }
    

When you run the project, Outlook starts. Open a message and then choose your app.

To test the mail app in Outlook

  1. On the menu bar, choose Debug, Start Debugging.

    The Connect to Exchange email account dialog box opens.

  2. Provide the email address and password for a server that is running Exchange 2013, and then choose Connect.

    Note Note

    If you are debugging your mail app by using Outlook Web App or OWA for Devices, you might receive a page that specifies that there is a problem with the website security certificate. If this page appears, choose the Continue to this website (not recommended) option. Then, you might have to provide a user name and password to the WAC again to begin testing your mail app.

  3. In Outlook, open any email message that you have previously sent or received. If you do not have any messages to open, send yourself an email message. After the message appears in the Inbox folder, open the message.

    An app button named MyFirstMailApp appears in the app pane above the email message.

  4. Choose the MyFirstMailApp button.

    The mail app opens and shows a table that contains the email address of the sender and the first recipient found in an email message.

    A search button appears beneath the table.

  5. Choose the search button to search the LinkedIn web site for people who share the same name as the sender.

Now that you’ve created a basic mail app, learn more about mail apps for Outlook and the fundamentals for developing mail apps in Outlook.

Show:
© 2014 Microsoft