Edit

Configure your Outlook add-in for event-based activation

  • Article

Without the event-based activation feature, a user has to explicitly launch an add-in to complete their tasks. This feature enables your add-in to run tasks based on certain events, particularly for operations that apply to every item. You can also integrate with the task pane and function commands.

By the end of this walkthrough, you'll have an add-in that runs whenever a new item is created and sets the subject.

Note

Support for this feature was introduced in requirement set 1.10, with additional events now available in subsequent requirement sets. For details about an event's minimum requirement set and the clients and platforms that support it, see Supported events and Requirement sets supported by Exchange servers and Outlook clients.

The add-in from the following walkthrough only runs in Outlook on Windows, on Mac, and on the web. To learn how to implement an event-based add-in that runs in Outlook on mobile devices, see Implement event-based activation in Outlook mobile add-ins.

Supported events

The following table lists events that are currently available and the supported clients for each event. When an event is raised, the handler receives an event object which may include details specific to the type of event. The Description column includes a link to the related object where applicable.

Event canonical name
and XML manifest name		 Unified manifest for Microsoft 365 name Description Minimum requirement set and supported clients
OnNewMessageCompose newMessageComposeCreated On composing a new message (includes reply, reply all, and forward) but not on editing, for example, a draft. 1.10

- Windows1
- Web browser
- New Mac UI
- Android2
- iOS2
OnNewAppointmentOrganizer newAppointmentOrganizerCreated On creating a new appointment but not on editing an existing one. 1.10

- Windows1
- Web browser
- New Mac UI
OnMessageAttachmentsChanged messageAttachmentsChanged On adding or removing attachments while composing a message.

Event-specific data object: AttachmentsChangedEventArgs		 1.11

- Windows1
- Web browser
- New Mac UI
OnAppointmentAttachmentsChanged appointmentAttachmentsChanged On adding or removing attachments while composing an appointment.

Event-specific data object: AttachmentsChangedEventArgs		 1.11

- Windows1
- Web browser
- New Mac UI
OnMessageRecipientsChanged messageRecipientsChanged On adding or removing recipients while composing a message.

Event-specific data object: RecipientsChangedEventArgs		 1.11

- Windows1
- Web browser
- New Mac UI
OnAppointmentAttendeesChanged appointmentAttendeesChanged On adding or removing attendees while composing an appointment.

Event-specific data object: RecipientsChangedEventArgs		 1.11

- Windows1
- Web browser
- New Mac UI
OnAppointmentTimeChanged appointmentTimeChanged On changing date/time while composing an appointment.

Event-specific data object: AppointmentTimeChangedEventArgs

Important: If you drag and drop an appointment to a different date/time slot on the calendar, the OnAppointmentTimeChanged event doesn't occur. It only occurs when the date/time is directly changed from an appointment.		 1.11

- Windows1
- Web browser
- New Mac UI
OnAppointmentRecurrenceChanged appointmentRecurrenceChanged On adding, changing, or removing the recurrence details while composing an appointment. If the date/time is changed, the OnAppointmentTimeChanged event also occurs.

Event-specific data object: RecurrenceChangedEventArgs		 1.11

- Windows1
- Web browser
- New Mac UI
OnInfoBarDismissClicked infoBarDismissClicked On dismissing a notification while composing a message or appointment item. Only the add-in that added the notification will be notified.

Event-specific data object: InfobarClickedEventArgs		 1.11

- Windows1
- Web browser
- New Mac UI
OnMessageSend messageSending On sending a message item. To learn more, see the Smart Alerts walkthrough. 1.12

- Windows1
- Web browser
- New Mac UI
OnAppointmentSend appointmentSending On sending an appointment item. To learn more, see the Smart Alerts walkthrough. 1.12

- Windows1
- Web browser
- New Mac UI
OnMessageCompose messageComposeOpened On composing a new message (includes reply, reply all, and forward) or editing a draft. 1.12

- Windows1
- Web browser
- New Mac UI
OnAppointmentOrganizer appointmentOrganizerOpened On creating a new appointment or editing an existing one. 1.12

- Windows1
- Web browser
- New Mac UI
OnMessageFromChanged Not available On changing the mail account in the From field of a message being composed. To learn more, see Automatically update your signature when switching between Exchange accounts. 1.13

- Windows1
- Web browser

Preview

- New Mac UI
OnAppointmentFromChanged Not available On changing the mail account in the organizer field of an appointment being composed. To learn more, see Automatically update your signature when switching between Exchange accounts. 1.13

- Web browser

Preview

- New Mac UI
OnSensitivityLabelChanged Not available On changing the sensitivity label while composing a message or appointment. To learn how to manage the sensitivity label of a mail item, see Manage the sensitivity label of your message or appointment in compose mode.

Event-specific data object: SensitivityLabelChangedEventArgs		 1.13

- Windows1
- Web browser

Preview

- New Mac UI

Note

1 Event-based add-ins in Outlook on Windows require a minimum of Windows 10 Version 1903 (Build 18362) or Windows Server 2019 Version 1903 to run.

2 Outlook on mobile supports APIs up to Mailbox requirement set 1.5. However, support is now enabled for additional APIs and features introduced in later requirement sets, such as the OnNewMessageCompose event. To learn more, see Implement event-based activation in Outlook mobile add-ins.

Set up your environment

Complete the Outlook quick start which creates an add-in project with the Yeoman generator for Office Add-ins.

Configure the manifest

To configure the manifest, select the tab for the type of manifest you are using.

To enable event-based activation of your add-in, you must configure the Runtimes element and LaunchEvent extension point in the VersionOverridesV1_1 node of the manifest.

  1. In your code editor, open the quick start project.

  2. Open the manifest.xml file located at the root of your project.

  3. Select the entire <VersionOverrides> node (including open and close tags) and replace it with the following XML, then save your changes.

<VersionOverrides xmlns="http://schemas.microsoft.com/office/mailappversionoverrides" xsi:type="VersionOverridesV1_0">
  <VersionOverrides xmlns="http://schemas.microsoft.com/office/mailappversionoverrides/1.1" xsi:type="VersionOverridesV1_1">
    <Requirements>
      <bt:Sets DefaultMinVersion="1.10">
        <bt:Set Name="Mailbox" />
      </bt:Sets>
    </Requirements>
    <Hosts>
      <Host xsi:type="MailHost">
        <!-- Event-based activation happens in a lightweight runtime.-->
        <Runtimes>
          <!-- HTML file including reference to or inline JavaScript event handlers.
               This is used by Outlook on the web and Outlook on the new Mac UI. -->
          <Runtime resid="WebViewRuntime.Url">
            <!-- JavaScript file containing event handlers. This is used by Outlook on Windows. -->
            <Override type="javascript" resid="JSRuntime.Url"/>
          </Runtime>
        </Runtimes>
        <DesktopFormFactor>
          <FunctionFile resid="Commands.Url" />
          <ExtensionPoint xsi:type="MessageReadCommandSurface">
            <OfficeTab id="TabDefault">
              <Group id="msgReadGroup">
                <Label resid="GroupLabel" />
                <Control xsi:type="Button" id="msgReadOpenPaneButton">
                  <Label resid="TaskpaneButton.Label" />
                  <Supertip>
                    <Title resid="TaskpaneButton.Label" />
                    <Description resid="TaskpaneButton.Tooltip" />
                  </Supertip>
                  <Icon>
                    <bt:Image size="16" resid="Icon.16x16" />
                    <bt:Image size="32" resid="Icon.32x32" />
                    <bt:Image size="80" resid="Icon.80x80" />
                  </Icon>
                  <Action xsi:type="ShowTaskpane">
                    <SourceLocation resid="Taskpane.Url" />
                  </Action>
                </Control>
                <Control xsi:type="Button" id="ActionButton">
                  <Label resid="ActionButton.Label"/>
                  <Supertip>
                    <Title resid="ActionButton.Label"/>
                    <Description resid="ActionButton.Tooltip"/>
                  </Supertip>
                  <Icon>
                    <bt:Image size="16" resid="Icon.16x16"/>
                    <bt:Image size="32" resid="Icon.32x32"/>
                    <bt:Image size="80" resid="Icon.80x80"/>
                  </Icon>
                  <Action xsi:type="ExecuteFunction">
                    <FunctionName>action</FunctionName>
                  </Action>
                </Control>
              </Group>
            </OfficeTab>
          </ExtensionPoint>

          <!-- Can configure other command surface extension points for add-in command support. -->

          <!-- Enable launching the add-in on the included events. -->
          <ExtensionPoint xsi:type="LaunchEvent">
            <LaunchEvents>
              <LaunchEvent Type="OnNewMessageCompose" FunctionName="onNewMessageComposeHandler"/>
              <LaunchEvent Type="OnNewAppointmentOrganizer" FunctionName="onNewAppointmentComposeHandler"/>
              
              <!-- Other available events -->
              <!--
              <LaunchEvent Type="OnMessageAttachmentsChanged" FunctionName="onMessageAttachmentsChangedHandler" />
              <LaunchEvent Type="OnAppointmentAttachmentsChanged" FunctionName="onAppointmentAttachmentsChangedHandler" />
              <LaunchEvent Type="OnMessageRecipientsChanged" FunctionName="onMessageRecipientsChangedHandler" />
              <LaunchEvent Type="OnAppointmentAttendeesChanged" FunctionName="onAppointmentAttendeesChangedHandler" />
              <LaunchEvent Type="OnAppointmentTimeChanged" FunctionName="onAppointmentTimeChangedHandler" />
              <LaunchEvent Type="OnAppointmentRecurrenceChanged" FunctionName="onAppointmentRecurrenceChangedHandler" />
              <LaunchEvent Type="OnInfoBarDismissClicked" FunctionName="onInfobarDismissClickedHandler" />
              <LaunchEvent Type="OnMessageSend" FunctionName="onMessageSendHandler" SendMode="PromptUser" />
              <LaunchEvent Type="OnAppointmentSend" FunctionName="onAppointmentSendHandler" SendMode="PromptUser" />
              <LaunchEvent Type="OnMessageCompose" FunctionName="onMessageComposeHandler" />
              <LaunchEvent Type="OnAppointmentOrganizer" FunctionName="onAppointmentOrganizerHandler" />
              -->
            </LaunchEvents>
            <!-- Identifies the runtime to be used (also referenced by the Runtime element). -->
            <SourceLocation resid="WebViewRuntime.Url"/>
          </ExtensionPoint>
        </DesktopFormFactor>
      </Host>
    </Hosts>
    <Resources>
      <bt:Images>
        <bt:Image id="Icon.16x16" DefaultValue="https://localhost:3000/assets/icon-16.png"/>
        <bt:Image id="Icon.32x32" DefaultValue="https://localhost:3000/assets/icon-32.png"/>
        <bt:Image id="Icon.80x80" DefaultValue="https://localhost:3000/assets/icon-80.png"/>
      </bt:Images>
      <bt:Urls>
        <bt:Url id="Commands.Url" DefaultValue="https://localhost:3000/commands.html" />
        <bt:Url id="Taskpane.Url" DefaultValue="https://localhost:3000/taskpane.html" />
        <bt:Url id="WebViewRuntime.Url" DefaultValue="https://localhost:3000/commands.html" />
        <!-- Entry needed for Outlook on Windows. -->
        <bt:Url id="JSRuntime.Url" DefaultValue="https://localhost:3000/launchevent.js" />
      </bt:Urls>
      <bt:ShortStrings>
        <bt:String id="GroupLabel" DefaultValue="Contoso Add-in"/>
        <bt:String id="TaskpaneButton.Label" DefaultValue="Show Taskpane"/>
        <bt:String id="ActionButton.Label" DefaultValue="Perform an action"/>
      </bt:ShortStrings>
      <bt:LongStrings>
        <bt:String id="TaskpaneButton.Tooltip" DefaultValue="Opens a pane displaying all available properties."/>
        <bt:String id="ActionButton.Tooltip" DefaultValue="Perform an action when clicked."/>
      </bt:LongStrings>
    </Resources>
  </VersionOverrides>
</VersionOverrides>

Outlook on Windows uses a JavaScript file, while Outlook on the web and on the new Mac UI use an HTML file that can reference the same JavaScript file. You must provide references to both these files in the Resources node of the manifest as the Outlook platform ultimately determines whether to use HTML or JavaScript based on the Outlook client. As such, to configure event handling, provide the location of the HTML in the <Runtime> element, then in its Override child element provide the location of the JavaScript file inlined or referenced by the HTML.

Tip

Implement event handling

You have to implement handling for your selected events.

In this scenario, you'll add handling for composing new items.

  1. From the same quick start project, create a new folder named launchevent under the ./src directory.

  2. In the ./src/launchevent folder, create a new file named launchevent.js.

  3. Open the file ./src/launchevent/launchevent.js in your code editor and add the following JavaScript code.

    /*
* Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
* See LICENSE in the project root for license information.
*/

function onNewMessageComposeHandler(event) {
  setSubject(event);
}
function onNewAppointmentComposeHandler(event) {
  setSubject(event);
}
function setSubject(event) {
  Office.context.mailbox.item.subject.setAsync(
    "Set by an event-based add-in!",
    {
      "asyncContext": event
    },
    function (asyncResult) {
      // Handle success or error.
      if (asyncResult.status !== Office.AsyncResultStatus.Succeeded) {
        console.error("Failed to set subject: " + JSON.stringify(asyncResult.error));
      }

      // Call event.completed() to signal to the Outlook client that the add-in has completed processing the event.
      asyncResult.asyncContext.completed();
    });
}

// IMPORTANT: To ensure your add-in is supported in the Outlook client on Windows, remember to map the event handler name specified in the manifest to its JavaScript counterpart.
if (Office.context.platform === Office.PlatformType.PC || Office.context.platform == null) {
  Office.actions.associate("onNewMessageComposeHandler", onNewMessageComposeHandler);
  Office.actions.associate("onNewAppointmentComposeHandler", onNewAppointmentComposeHandler);
}

  4. Save your changes.

Note

There are some limitations you must be aware of when developing an event-based add-in for Outlook on Windows. To learn more, see Event-based activation behavior and limitations.

Update the commands HTML file

  1. In the ./src/commands folder, open commands.html.

  2. Immediately before the closing head tag (</head>), add a script entry to include the event-handling JavaScript code.

    <script type="text/javascript" src="../launchevent/launchevent.js"></script>

  3. Save your changes.

Update webpack config settings

  1. Open the webpack.config.js file found in the root directory of the project and complete the following steps.

  2. Locate the plugins array within the config object and add this new object at the beginning of the array.

    new CopyWebpackPlugin({
  patterns: [
    {
      from: "./src/launchevent/launchevent.js",
      to: "launchevent.js",
    },
  ],
}),

  3. Save your changes.

Try it out

  1. Run the following commands in the root directory of your project. When you run npm start, the local web server will start (if it's not already running) and your add-in will be sideloaded.

    npm run build

    npm start

    Note

    If your add-in wasn't automatically sideloaded, then follow the instructions in Sideload Outlook add-ins for testing to manually sideload the add-in in Outlook.

  2. In Outlook on the web, create a new message.

    A message window in Outlook on the web with the subject set on compose.

  3. In Outlook on the new Mac UI, create a new message.

    A message window in Outlook on the new Mac UI with the subject set on compose.

  4. In Outlook on Windows, create a new message.

    A message window in Outlook on Windows with the subject set on compose.

Troubleshooting guide

As you develop your event-based add-in, you may need to troubleshoot issues, such as your add-in not loading or the event not occurring. If you run into development issues, refer to the next four sections for troubleshooting guidance.

Review event-based activation prerequisites

Check manifest and JavaScript requirements

  • Ensure that the following conditions are met in your add-in's manifest.

    • Verify that your add-in's source file location URL is publicly available and isn't blocked by a firewall. This URL is specified in your manifest's SourceLocation element.

    • Verify that the <Runtimes> element (XML manifest) or "code" object (unified manifest (preview)) correctly references the HTML or JavaScript file containing the event handlers. Outlook on Windows uses the JavaScript file during runtime, while Outlook on the web and on new Mac UI use the HTML file. For an example of how this is configured in the manifest, see Configure the manifest.

      For Outlook on Windows, you must bundle all your event-handling JavaScript code into this JavaScript file referenced in the manifest. Note that a large JavaScript bundle may cause issues with the performance of your add-in. We recommend preprocessing heavy operations, so that they're not included in your event-handling code.

  • Verify that your event-handling JavaScript file referenced by the Outlook client on Windows calls Office.actions.associate. This ensures that the event handler name specified in the manifest is mapped to its JavaScript counterpart.

    Tip

    If your event-based add-in has only one JavaScript file referenced by Outlook on the web, Windows, and Mac, it's recommended to check on which platform the add-in is running to determine when to call Office.actions.associate, as shown in the following code.

    if (Office.context.platform === Office.PlatformType.PC || Office.context.platform == null) {
  Office.actions.associate("onNewMessageComposeHandler", onNewMessageComposeHandler);
  Office.actions.associate("onNewAppointmentComposeHandler", onNewAppointmentComposeHandler);
}

  • The JavaScript code of event-based add-ins that run in Outlook on Windows only supports ECMAScript 2016 and earlier specifications. Some examples of programming syntax to avoid are as follows.

    • Avoid using async and await statements in your code. Including these in your JavaScript code will cause the add-in to time out.
    • Avoid using the conditional (ternary) operator as it will prevent your add-in from loading.

    If your add-in has only one JavaScript file referenced by Outlook on the web, Windows, and Mac, you must limit your code to ECMAScript 2016 to ensure that your add-in runs in Outlook on Windows. However, if you have a separate JavaScript file referenced by Outlook on the web and Mac, you can implement a later ECMAScript specification in that file.

Debug your add-in

  • As you make changes to your add-in, be aware that:

    • If you update the manifest, remove the add-in, then sideload it again. If you're using Outlook on Windows, you must also close and reopen Outlook.
    • If you make changes to files other than the manifest, close and reopen the Outlook desktop client, or refresh the browser tab running Outlook on the web.
    • If you're still unable to see your changes after performing these steps, clear your Office cache.

  • As you test your add-in in Outlook on Windows:

    • Check Event Viewer for any reported add-in errors.

      1. In Event Viewer, select Windows Logs > Application.
      2. From the Actions panel, select Filter Current Log.
      3. From the Logged dropdown, select your preferred log time frame.
      4. Select the Error checkbox.
      5. In the Event IDs field, enter 63.
      6. Select OK to apply your filters.

      A sample of Event Viewer's Filter Current Log settings configured to only show Outlook errors with event ID 63 that occurred in the last hour.

    • Verify that the bundle.js file is downloaded to the following folder in File Explorer. Replace text enclosed in [] with your applicable information.

      %LOCALAPPDATA%\Microsoft\Office\16.0\Wef\{[Outlook profile GUID]}\[Outlook mail account encoding]\Javascript\[Add-in ID]_[Add-in Version]_[locale]

      Tip

      If the bundle.js file doesn't appear in the Wef folder, try the following:

  • As you test your add-in in Outlook on Windows or Mac, enable runtime logging to identify possible manifest and add-in installation issues. For guidance on how to use runtime logging, see Debug your add-in with runtime logging.

  • Set breakpoints in your code to debug your add-in. For platform-specific instructions, see Debug your event-based Outlook add-in.

Seek additional help

If you still need help after performing the recommended troubleshooting steps, open a GitHub issue. Include screenshots, video recordings, or runtime logs to supplement your report.

Deploy to users

Event-based add-ins are restricted to admin-managed deployments only, even if they're acquired from AppSource. If users acquire the add-in from AppSource or the in-app Office Store, they won't be able to activate the event-based function of the add-in. To learn more about listing your event-based add-in in AppSource, see AppSource listing options for your event-based Outlook add-in.

Admin deployments are done by uploading the manifest to the Microsoft 365 admin center. In the admin portal, expand the Settings section in the navigation pane then select Integrated apps. On the Integrated apps page, choose the Upload custom apps action.

The Integrated apps page on the Microsoft 365 admin center with the Upload custom apps action highlighted.

Important

Add-ins that use the Smart Alerts feature can only be published to AppSource if the manifest's send mode property is set to the prompt user or soft block option. If an add-in's send mode property is set to block, it can only be deployed by an organization's admin as it will fail AppSource validation.

Deploy manifest updates

Because event-based add-ins are deployed by admins, any change you make to the manifest requires admin consent through the Microsoft 365 admin center. Until the admin accepts your changes, users in their organization are blocked from using the add-in. To learn more about the admin consent process, see Admin consent for installing event-based add-ins.

Event-based activation behavior and limitations

Add-in launch-event handlers are expected to be short-running, lightweight, and as noninvasive as possible. After activation, your add-in will time out within approximately 300 seconds, the maximum length of time allowed for running event-based add-ins. To signal that your add-in has completed processing a launch event, your associated event handler must call the event.completed method. (Note that code included after the event.completed statement isn't guaranteed to run.) Each time an event that your add-in handles is triggered, the add-in is reactivated and runs the associated event handler, and the timeout window is reset. The add-in ends after it times out, or the user closes the compose window or sends the item.

If the user has multiple add-ins that subscribed to the same event, the Outlook platform launches the add-ins in no particular order. Currently, only five event-based add-ins can be actively running.

In all supported Outlook clients, the user must remain on the current mail item where the add-in was activated for it to complete running. Navigating away from the current item (for example, switching to another compose window or tab) terminates the add-in operation. The add-in also ceases operation when the user sends the message or appointment they're composing.

When developing an event-based add-in to run in the Outlook on Windows client, be mindful of the following:

  • Imports aren't supported in the JavaScript file where you implement the handling for event-based activation.

  • Add-ins don't run code included in Office.onReady() and Office.initialize. We recommend adding any startup logic, such as checking the user's Outlook version, to your event handlers instead.

  • Only the JavaScript file referenced in the manifest is supported for event-based activation. You must bundle your event-handling JavaScript code into this single file. The location of the referenced JavaScript file in the manifest varies depending on the type of manifest your add-in uses.

    • XML manifest: <Override> child element of the <Runtime> node
    • Unified manifest for Microsoft 365 (preview): "script" property of the "code" object

    Note that a large JavaScript bundle may cause issues with the performance of your add-in. We recommend preprocessing heavy operations, so that they're not included in your event-handling code.

Some Office.js APIs that change or alter the UI aren't allowed from event-based add-ins. The following are the blocked APIs.

Preview features in event handlers (Outlook on Windows)

Outlook on Windows includes a local copy of the production and beta versions of Office.js instead of loading from the content delivery network (CDN). By default, the local production copy of the API is referenced. To reference the local beta copy of the API, you must configure your computer's registry. This will enable you to test preview features in your event handlers in Outlook on Windows.

  1. In the registry, navigate to HKEY_CURRENT_USER\SOFTWARE\Microsoft\Office\16.0\Outlook\Options\WebExt\Developer. If the key doesn't exist, create it.

  2. Create an entry named EnableBetaAPIsInJavaScript and set its value to 1.

    The EnableBetaAPIsInJavaScript registry value is set to 1."

Enable single sign-on (SSO)

To enable SSO in your event-based add-in, you must add its JavaScript file to a well-known URI. For guidance on how to configure this resource, see Enable single sign-on (SSO) or cross-origin resource sharing (CORS) in your event-based Outlook add-in.

Request external data

You can request external data by using an API like Fetch or by using XMLHttpRequest (XHR), a standard web API that issues HTTP requests to interact with servers.

Be aware that you must use additional security measures when using XMLHttpRequest objects, requiring Same Origin Policy and simple CORS (Cross-Origin Resource Sharing).

A simple CORS implementation:

  • Can't use cookies.
  • Only supports simple methods, such as GET, HEAD, and POST.
  • Accepts simple headers with field names Accept, Accept-Language, or Content-Language.
  • Can use the Content-Type, provided that the content type is application/x-www-form-urlencoded, text/plain, or multipart/form-data.
  • Can't have event listeners registered on the object returned by XMLHttpRequest.upload.
  • Can't use ReadableStream objects in requests.

To enable your event-based add-in to make CORS request, you must add the add-in and its JavaScript file to a well-known URI. For guidance on how to configure this resource, see Enable single sign-on (SSO) or cross-origin resource sharing (CORS) in your event-based Outlook add-in.

Note

Full CORS support is available in Outlook on the web, Mac, and Windows (starting in Version 2201, Build 16.0.14813.10000).

See also