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 add-in for Outlook by using a text editor

Office Add-ins

Learn how to use a text editor to create a simple mail app for Outlook.

Last modified: July 15, 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 the mail app for Outlook
Create the manifest file
Deploy the source
Install the mail app
Next steps
Additional resources

You can use a text editor to create a simple mail app for Outlook. The mail app example described in this article creates a table that contains the email address of the sender and the first recipient found in a message. It uses version 1.1 of the JavaScript API for Office and apps for Office manifest schema.

After you create your first mail app by using a text editor, you can learn more about the fundamentals for developing mail apps for Outlook.

Before you begin, make sure that you have access to the following:

  • A text editor

  • A computer that is running Exchange Online, Exchange Online as part of Office 365, or an on-premises version of Exchange starting with Exchange Server 2013 Service Pack 1 (SP1)

  • A web server that your Exchange server can access

A mail app for Outlook is an HMTL document that includes JavaScript code. The user interface for the mail app is provided by a standard HTML file with JavaScript. Use the following steps to create a simple UI for a mail app.

To create a mail app

  1. Create a file named "default.htm" that contains the following HTML code.

    <!DOCTYPE html>
        <meta http-equiv="X-UA-Compatible" content="IE=Edge" >
        <!-- The title element is optional and will not be displayed anywhere. -->
        <title>Sender and Recipient</title>
    <body style="margin: 4px">
        <h3>Email Details</h3>
           <tr><td>Display Name</td><td id="senderDisplayName" /><td id="recipientDisplayName" /></tr>
           <tr><td>Email Address</td><td id="senderEmailAddress" /><td id="recipientEmailAddress" /></tr>
  2. Add references to the mail app JavaScript API by adding the following code to the head element.

    Note Note

    The script element must be closed with a </script> tag so that the script block is correctly processed by all browsers.

    <!-- Add these two references to MicrosoftAjax.js and Office.js. -->
        <script src="https://ajax.aspnetcdn.com/ajax/jQuery/jquery-1.11.2.min.js"></script>
        <script src="https://appsforoffice.microsoft.com/lib/1.1/hosted/Office.js" type="text/javascript"></script>
  3. Create the initialization function that the client will call to initialize your mail app. In this example, the initialization function creates a table that contains the sender and recipient of the selected message.

    In the complete app, the initialization function is included in a script block in the HTML document, but the function can be in a separate JavaScript file that is included in the HTML files.

        <script type="text/javascript">
            Global variables to hold references to the host application object that provides access to
            the Framework APIs and the settings of your mail app.
            var outlook;
            var settings;
            When the Framework is ready, the initialize() method will be called.
            This method is the entry point for your code.
            // The initialize function is required for all apps.
            Office.initialize = function () {
            // Checks for the DOM to load using the jQuery ready function.
                $(document).ready(function () {
                // After the DOM is loaded, app-specific code can run.
                    mailbox = Office.context.mailbox;
                    settings = Office.context.roamingSettings;
                    /* mail app code goes here */
  4. Add the JavaScript code that gets the sender and recipient information for the first recipient in the recipient list and displays it on the mail app pane.

    document.getElementById("senderDisplayName").innerText = mailbox.item.sender.displayName;
    document.getElementById("senderEmailAddress").innerText = mailbox.item.sender.emailAddress;
    document.getElementById("recipientDisplayName").innerText = mailbox.item.to[0].displayName;
    document.getElementById("recipientEmailAddress").innerText = mailbox.item.to[0].emailAddress;
  5. Save the file as default.htm.

The manifest file provides the location of the mail app HTML file and the location of other information about your app, such as the display name and description. It also defines the set of criteria that must be met in order to activate your mail app and show its UI via Outlook.

Each app has a unique identifier that you have to generate and include in the manifest file. The identifier is a UUID. You can use a standard GUID generation tool, such as guidgen.exe (a Visual Studio tool), to generate the identifier. For more information, see Create GUID (guidgen.exe).

This simple manifest file shows your mail app for every email message, meeting request, meeting response, or meeting cancellation that is displayed Outlook.

Update the following with the app identifier and the URL of the source location that contains your mail app HTML, and then save it with the file name manifest.xml.

<?xml version="1.0" encoding="utf-8"?>

<OfficeApp xmlns="http://schemas.microsoft.com/office/appforoffice/1.1" 
  <!-- Id is a unique UUID for the mail app -->
  <DisplayName DefaultValue="First" />
  <Description DefaultValue="A simple first mail app." />

    <Sets DefaultMinVersion="1.1">
      <Set Name="Mailbox" />

    <Form xsi:type="ItemRead">
        <!-- Specify your web server and path in place of 'webserver'. -->
        <SourceLocation DefaultValue="https://webserver/default.htm" />

  <Rule xsi:type="ItemIs" FormType="Read" ItemType="Message" />

Your web server must have a valid certificate that traces to a trusted root certificate; otherwise, your mail app will fail with authentication errors. For more information about using a self-signed certificate for testing, see Create a Self-Signed Server Certificate in IIS 7.

The mail app source must be available on a web server to which the Exchange server can create an HTTP connection. You can use any standard method for deploying the required files to your web server. The following files must be stored on your web server:

  • default.htm — The HTML/JavaScript source files for your mail app.

  • manifest.xml — The XML manifest file that describes your mail app.

You can use the Exchange Admin Center (EAC) to install a mail app.

To install a mail app

  1. Open the EAC by using a URL that resembles the following:

    https://<exchange server>/ecp/

  2. Log on to the Exchange server by using a valid user name and password.

  3. Choose Manage apps to open the mail app manager.

    Note Note

    If you are logged on as the Exchange server administrator, you must first select the user name in the upper-right corner, and then choose My Options to open the account control panel.

  4. Select the plus sign (+) to add a new mail app.

  5. From the drop-down list, select Add from URL.

  6. Enter the fully qualified URL of the manifest file that you deployed earlier to your web server, and then choose Install.

  7. Select the user name in the upper-right corner of the window and select My Mail to switch to your email to test the mail app.

Now that you’ve created a basic mail app, learn more about mail apps for Outlook and the fundamentals for developing mail apps in Outlook.

© 2015 Microsoft