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.

    Note

    If you're asked to log in repeatedly then Basic Auth may be disabled for accounts on your Office 365 tenant. Try sideloading the manifest.

  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 task pane.

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

    Note

    If the task pane doesn't load, try to verify by opening it in a browser on the same machine.

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.