Build your first Outlook Add-in

In this article, you'll walk through the process of building an Outlook Add-in by using jQuery and the Office JS API.

Create the add-in

You can create an Office Add-in by using Visual Studio or any other editor. Tell us what editor you'd like to use by choosing one of the following tabs:

Prerequisites

Create the add-in project

  1. On the Visual Studio menu bar, choose File > New > Project.

  2. In the list of project types under Visual C# or Visual Basic, expand Office/SharePoint, choose Add-ins, and then choose Outlook Web Add-in as the project type.

  3. Name the project, and then choose OK.

  4. Visual Studio creates a solution and its two projects appear in Solution Explorer. The MessageRead.html file opens in Visual Studio.

Explore the Visual Studio solution

When you've completed the wizard, Visual Studio creates a solution that contains two projects.

Project Description
Add-in project Contains only an XML manifest file, which contains all the settings that describe your add-in. These settings help the Office host determine when your add-in should be activated and where the add-in should appear. Visual Studio generates the contents of this file for you so that you can run the project and use your add-in immediately. You can change these settings any time by modifying the XML file.
Web application project Contains the content pages of your add-in, including all the files and file references that you need to develop Office-aware HTML and JavaScript pages. While you develop your add-in, Visual Studio hosts the web application on your local IIS server. When you're ready to publish the add-in, you'll need to deploy this web application project to a web server.

Update the code

  1. MessageRead.html specifies the HTML that will be rendered in the add-in's task pane. In MessageRead.html, replace the <body> element with the following markup and save the file.

    <body class="ms-font-m ms-welcome">
        <div class="ms-Fabric content-main">
            <h1 class="ms-font-xxl">Message properties</h1>
            <table class="ms-Table ms-Table--selectable">
                <thead>
                    <tr>
                        <th>Property</th>
                        <th>Value</th>
                    </tr>
                </thead>
                <tbody class="prop-table"/>
            </table>
        </div>
    </body>
    
  2. Open the file MessageRead.js in the root of the web application project. This file specifies the script for the add-in. Replace the entire contents with the following code and save the file.

    'use strict';
    
    (function () {
    
      // The initialize function must be run each time a new page is loaded
      Office.initialize = function (reason) {
        $(document).ready(function () {
          loadItemProps(Office.context.mailbox.item);
        });
      };
    
      function loadItemProps(item) {
        // Get the table body element
        var tbody = $('.prop-table');
    
        // Add a row to the table for each message property
        tbody.append(makeTableRow("Id", item.itemId));
        tbody.append(makeTableRow("Subject", item.subject));
        tbody.append(makeTableRow("Message Id", item.internetMessageId));
        tbody.append(makeTableRow("From", item.from.displayName + " &lt;" +
          item.from.emailAddress + "&gt;"));
      }
    
      function makeTableRow(name, value) {
        return $("<tr><td><strong>" + name + 
          "</strong></td><td class=\"prop-val\"><code>" +
          value + "</code></td></tr>");
      }
    
    })();
    
  3. Open the file MessageRead.css in the root of the web application project. This file specifies the custom styles for the add-in. Replace the entire contents with the following code and save the file.

    html,
    body {
        width: 100%;
        height: 100%;
        margin: 0;
        padding: 0;
    }
    
    td.prop-val {
        word-break: break-all;
    }
    
    .content-main {
        margin: 10px;
    }
    

Update the manifest

  1. Open the XML manifest file in the Add-in project. This file defines the add-in's settings and capabilities.

  2. The ProviderName element has a placeholder value. Replace it with your name.

  3. The DefaultValue attribute of the DisplayName element has a placeholder. Replace it with My Office Add-in.

  4. The DefaultValue attribute of the Description element has a placeholder. Replace it with My First Outlook Add-in.

  5. Save the file.

    ...
    <ProviderName>Jason Johnston</ProviderName>
    <DefaultLocale>en-US</DefaultLocale>
    <!-- The display name of your add-in. Used on the store and various places of the Office UI such as the add-ins dialog. -->
    <DisplayName DefaultValue="My Office Add-in" />
    <Description DefaultValue="My First Outlook Add-in"/>
    ...
    

Try it out

  1. Using Visual Studio, test the newly created Outlook Add-in by pressing F5 or choosing the Start button to launch Outlook on the web. The add-in will be hosted locally on IIS.

  2. In Outlook on the web, select or open a message.

  3. Within the message, locate the add-in's button.

    A screenshot of a message window in Outlook on the web with the add-in button highlighted

  4. Click the button to open the add-in's taskpane.

    A screenshot of the add-in's taskpane in Outlook on the web displaying message properties

Next steps

Congratulations, you've successfully created your first Outlook Add-in! Next, learn more about the capabilities of an Outlook Add-in and build a more complex add-in by following along with the Advanced Outlook Add-in tutorial.