Was this page helpful?
Your feedback about this content is important. Let us know what you think.
Additional feedback?
1500 characters remaining
Export (0) Print
Expand All

Create your first mail app for Outlook by using Visual Studio

apps for Office

Develop and test a mail app for Outlook by using Visual Studio.

Last modified: June 22, 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
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
Additional resources

This article 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 article also shows you how to display some basic information from the web by using the sender name of the mail.

Note Note

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

Install the following before you get started:

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 Get started creating a mail app for Outlook with 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 website for people who share the same name as the sender.

Show:
© 2015 Microsoft