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

Create a mail add-in for Outlook with Napa Office 365 Development Tools

Office Add-ins

Use Napa Office 365 Development Tools to create a mail add-in for Outlook.

Last modified: August 12, 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
Create a basic mail add-in for Outlook
Change the properties of the add-in
Extract addresses from Outlook items
Show the history of property values for a selected address
Debug your mail add-in in Internet Explorer
Next Steps
Additional resources

Note Note

You can also build a mail add-in by using Visual Studio or a text editor. If you're not sure which tool to use, see Development basics.

The mail add-in you'll create here lets users view the history of property values for all of the addresses that appear in the body of the currently open email message. You'll see how to get information from an open item. In your add-in, you might use an address to get information from a service like a map, or more information about the value of a property, sales history, or real estate taxes.

After you've created your first mail add-in using Napa, learn more about mail add-ins, and the fundamentals for developing mail add-ins in Outlook.

Here's what you need to complete this walkthrough:

First, you'll create a basic mail add-in for Outlook.

To create a basic mail add-in for Outlook

  1. Open the Napa Office 365 Development Tools web app in your browser.

  2. Choose the Add New Project tile.

    Note: The Add New Project tile appears only if you've created other projects. If this is your first project, skip to the next step.

    Figure 1. New project tile

    Projects page
  3. Choose the Mail Add-in for Office tile, name the project MyFirstMailApp, and then choose the Create button.

    Figure 2. Mail add-in project tile

    Mail app project tile

    The code editor opens and shows the default webpage (named Home.html), which already contains some sample code that you can run without doing anything else.

  4. In the Home.html file, replace the opening and closing <body> tags with this code.

    <body>
    <!-- Page content -->
    <div id="content-main">
    <div class="padding">
    <p><strong>Select an address to view the property value history:</strong></p>
      <form name= "addressForm"" id="addresses">
                        <table>
    <tr>
                                <td>
                                    <table id="addressOptions"></table>
                                </td>
        </tr>
                         </table>
                     </form>
     <div id="valueWidget"></div>
    </div>
    </div>
    <div id="content-footer">
    <div class="padding">
    </div>
    </div>
    </body>
    

    The code adds a table that'll contain a list of addresses and a section that'll contain the history of property values.

Now, you'll specify a name and description for your add-in. Then, you'll apply activation rules to the add-in so that your mail add-in appears only next to mail items that have addresses in them.

To change the properties of the add-in

  1. At the side of the page, choose the Properties button (Properties button).

    The properties of the mail add-in appear.

  2. Set the Name, and Description properties to the values shown in Figure 3.

    Figure 3. General tab of the Properties page

    Properties page screenshot

    The Name and Description properties help users understand the purpose of the Office Add-in when it appears in a list of available add-ins for an Office application.

  3. Choose the Read tab.

  4. Select the Subject or body of the item contains a known entity box.

  5. In the Subject or body of the item contains a known entity list, choose Address.

    These rules ensure that your add-in appears only next to mail items that have addresses in them.

    Figure 4. Activation rules that ensure that your mail add-in appears only next to mails that contain addresses

    Activation rules screenshot
    Note Note

    This example only works with addresses in the United States. However, there's a work around using well-known entities. For more information, see Matching strings in an Outlook item as well-known entities.

  6. Choose the Apply button at the bottom of the Properties dialog box to save the property values.

    Note Note

    The Properties editor shows the most common settings of a mail add-in. It doesn't show all of the possible settings of a mail add-in. If your scenario requires you to modify settings that don't appear in the Properties editor, you can create your add-in by using Visual Studio or a text editor.

  7. Choose the Explore button (Explore button) on the left side of the page to return to the project view.

Your mail add-in can identify and get certain strings in the subject and body of the current Outlook item, including addresses, contacts, email addresses, meeting suggestions, phone numbers, task suggestions, and URLs. Next, you'll get an array of addresses from the body of the current Outlook item and show those addresses in the mail add-in.

To view examples of getting other types of strings, see Extract entity strings from an Outlook item.

To extract addresses from Outlook items

  1. Go to the Home.js file.

  2. In the code editor, open the Home.js file, and replace the contents of the file with this code.

    /// <reference path="../App.js" />
    /*global app*/
    
    (function () {
    'use strict';
    
    // The Office initialize function must be run each time a new page is loaded
    Office.initialize = function (reason) {
    $(document).ready(function () {
    app.initialize();
           $('#addresses').click(getSelectedAddress);
       getAddresses();
       
    });
    };
    })();
    
    function getAddresses() {
        var item = Office.context.mailbox.item;
        var entities = item.getEntities();
        var addressesArray = entities.addresses;
        
        for (var i = 0; i < addressesArray.length; i++) {
        var src = "<tr><td><Input type='radio' name='address' value='" + addressesArray[i] +
                      "'></td><td>" + addressesArray[i] + "</td></tr>";
      
            $('#addressOptions').append($(src));
    
          }
    }
    
    

Now, you’ll add code that runs when the user chooses an address in the add-in. The code shows a line chart of property values over the past year for the chosen address.

To show the history of property values for the selected address

  1. Go to the Home.js file.

  2. In the code editor, open the Home.js file, and add these functions.

    function ShowPropertyValues(address) {
    
        var encodedAddress = encodeURIComponent(address);
    
        var src = "<iframe height='300' width='300' " +
                  "src='https://www.zillow.com/widgets/zestimate/ZestimateLargeWidget.htm?" +
                  "did=zillow-shv-large-iframe-widget&type=iframe&address=" +
                   encodedAddress + "&searchbox=no&skinnyWidget=true&tc=566276&bgc=e2e7eb'></iframe>";
    
        $('#valueWidget').empty();
        $('#valueWidget').append($(src));
    }
    
    function getSelectedAddress() {
    
        var selectedItem = "";
    
        for (i = 0; i < document.addressForm.address.length; i++) {
    
            if (document.addressForm.address[i].checked) {
                selectedItem = document.addressForm.address[i].value;
            }
        }
        if (selectedItem === "") {
            selectedItem = document.addressForm.address.defaultValue;
        }
    ShowPropertyValues(selectedItem);
    }
    
    

Run it!

  1. On the side of the page, choose the Run button (Run button).

    A dialog box appears that prompts you to enter your email address and password.

  2. Enter the email address and password for a server that is running Exchange Server 2013, and then choose Continue.

  3. In Outlook, send yourself an email message that contains one or more addresses.

  4. After the message appears in the Inbox folder, open the message.

  5. At the top of the message, choose MyFirstMailApp.

    The MyFirstMailApp add-in opens. The addresses appear as options in the add-in.

  6. Choose an address from the list.

    The history of property values associated with that address appears in a chart.

  7. Close Outlook.

If you use Internet Explorer (IE) 9 and up, you can use F12 developer tools to debug the JavaScript, HTML, and Cascading Style Sheets (CSS) of your mail add-in.

Here's how to open F12 tools, start the debugger, and cause execution to stop on a line of code in your Home.js file.

To get started debugging your mail add-in in Internet Explorer

  1. At the bottom of the page, choose the Run button (Run button).

    A dialog box appears that asks you for your email address and password.

  2. Enter the email address and password for a server that is running Exchange Server 2013, and then choose Continue.

  3. Open the message that contains the address.

  4. At the top of the message, choose MyFirstMailApp.

    The MyFirstMailApp add-in opens.

  5. In Outlook, select the mail add-in so that the add-in is in focus when you start the debugging tools.

  6. Press the F12 key on your keyboard.

    The F12 tools open in a separate window.

  7. In the F12 tools window, choose the Script tab, and then choose the Start debugging button.

  8. From the View Sources drop-down list under the Stop debugging button, select Home.js.

    The content of the MyAppPage file appears in the left pane of the window.

  9. Set a breakpoint next to the getSelectedAddress method.

    For more information about how to set a breakpoint in the F12 tool window, see Breaking Code Execution.

  10. On the shortcut menu for the mail add-in, choose Refresh.

  11. Choose an address from the list.

    In the F12 tools window, execution stops on the getSelectedAddress method.

    See these topics for more information.

    If you use a browser other than Internet Explorer, search your browser documentation.

Now that you've created a basic mail add-in, consider exploring the following paths:

Show:
© 2015 Microsoft