Outlook Add-ins Quick Start

Welcome to the quick start guide for developing Outlook add-ins! This tutorial will walk you through the essential steps to create your first Outlook add-in using Node.js and Yeoman generator for Office. You'll build a simple add-in that adds a button to the Outlook ribbon and displays a task pane with custom content.

Prerequisites

Before you begin, ensure you have the following installed:

Step 1: Create Your Add-in Project

Use the Yeoman generator to create a new Outlook add-in project. Open your terminal or command prompt and run:

yo office

Follow the prompts:

  1. Choose a type for your project: Select Office Add-in Project.
  2. Choose a script type: Select JavaScript.
  3. What do you want to name your add-in?: Enter MyOutlookAddin.
  4. Which Office client application would you like to support?: Select Outlook.
  5. Which type of Outlook add-in would you like to create?: Select Outlook Add-in using Task Pane and Single(Shared) Runtime.

Step 2: Explore the Project Structure

Navigate into your newly created project directory:

cd MyOutlookAddin

Open the project in your favorite code editor. Key files include:

Step 3: Run Your Add-in

To run your add-in, use the following command in your project directory:

npm start

This command will:

  1. Compile your code.
  2. Start a local web server.
  3. Open Outlook (if installed) and sideload your add-in.

You might need to explicitly trust the add-in. Follow the on-screen instructions in Outlook.

Step 4: Test Your Add-in

Once Outlook opens and your add-in is loaded:

  1. Navigate to an email or appointment.
  2. You should see a new button on the Outlook ribbon (e.g., "Show Taskpane"). Click it.
  3. A task pane will appear on the right side of the Outlook window.

Step 5: Customize Your Add-in

Let's make a small customization. Open src/taskpane/taskpane.html and modify the content inside the <body> tag:

<body>
    <section id="container" class="message-body" aria-label="Content for the task pane" role="region">
        <h2>My Custom Outlook Add-in</h2>
        <p>This is where your add-in magic happens!</p>
        <button id="show-msg-button">Get Email Subject</button>
        <p id="subject-display"></p>
    </section>
</body>

Now, let's add some logic in src/taskpane/taskpane.js to get the email subject when the button is clicked:

(function () {
    "use strict";

    // The initialize function is run when the add-in is loaded.
    Office.onReady(function () {
        $(document).ready(function () {
            if (Office.isSet("Mailbox", "1.9")) {
                $('#show-msg-button').prop('disabled', false);
            }
            $('#show-msg-button').on('click', showEmailSubject);
        });
    });

    function showEmailSubject() {
        Office.context.mailbox.item.subject.getAsync(
            function (asyncResult) {
                if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
                    $('#subject-display').text("Email Subject: " + asyncResult.value);
                } else {
                    $('#subject-display').text("Error getting subject: " + asyncResult.error.message);
                }
            }
        );
    }
})();

Save these files. Your browser should automatically refresh, or you may need to restart the add-in (Ctrl+R or Cmd+R in Outlook). Now, clicking the "Get Email Subject" button should display the subject of the current email.

Tip: For more complex add-ins, consider using frameworks like React or Angular. The Yeoman generator also supports these options.

Next Steps

Congratulations on building your first Outlook add-in! You've learned how to:

Continue exploring the API Reference to discover more capabilities for interacting with Outlook data, creating rich user experiences, and integrating with other services.

Next: Excel Add-ins Quick Start