Edit

Implement event-based activation in Outlook mobile add-ins

  • Article

With the event-based activation feature, develop an add-in to automatically activate and complete operations when certain events occur in Outlook on Android or on iOS, such as composing a new message.

The following sections walk you through how to develop an Outlook mobile add-in that automatically adds a signature to new messages being composed. This highlights a sample scenario of how you can implement event-based activation in your mobile add-in. Significantly enhance the mobile user experience by exploring other scenarios in your add-in today.

To learn how to implement an event-based add-in for Outlook on Windows (classic and new (preview)), on Mac, and on the web, see Configure your Outlook add-in for event-based activation.

Note

Outlook on Android and on iOS only support up to Mailbox requirement set 1.5. However, to support the event-based activation feature, some APIs from later requirement sets have been enabled on mobile clients. For more information on this exception, see Additional supported APIs.

Supported clients

The add-in you develop in this walkthrough is supported in Outlook on Android and on iOS starting in Version 4.2352.0. You must have a Microsoft 365 subscription to run the feature.

Set up your environment

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

Configure the manifest

The steps for configuring the manifest depend on which type of manifest you selected in the quick start.

  1. Configure the "extensions.runtimes" property just as you would for setting up a function command. For details, see Configure the runtime for the function command.

  2. In the "extensions.ribbons.contexts" array, add mailRead as an item. When you're finished, the array should look like the following.

    "contexts": [
    "mailRead"
],

  3. In the "extensions.ribbons.requirements.formFactors" array, add "mobile" as an item. When you're finished, the array should look like the following.

    "formFactors": [
    "mobile",
    <!-- Typically there will be other form factors listed. -->
]

  4. Add the following "autoRunEvents" array as a property of the object in the "extensions" array.

    "autoRunEvents": [

]

  5. Add an object like the following to the "autoRunEvents" array. Note the following about this code:

    • The "events" property maps handlers to events.
    • The "events.type" must be one of the types listed at Supported events.
    • The value of the "events.actionId" is the name of a function that you create in Implement the event handler.
    • You can have more than one object in the "events" array.
      {
      "requirements": {
          "capabilities": [
              {
                  "name": "Mailbox",
                  "minVersion": "1.10"
              }
          ],
          "scopes": [
              "mail"
          ]
      },
      "events": [
          {
              "type": "newMessageComposeCreated",
              "actionId": "onNewMessageComposeHandler"
          },
      ]
  }

Tip

To learn more about manifests for Outlook add-ins, see Office Add-ins manifest and Add support for add-in commands in Outlook on mobile devices.

Implement the event handler

To enable your add-in to complete tasks when the OnNewMessageCompose event occurs, you must implement a JavaScript event handler. In this section, you'll create the onNewMessageComposeHandler function that adds a signature to a new message being composed, then shows a message to notify that the signature was added.

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

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

  3. Open the launchevent.js file you created 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.
*/

// Add start-up logic code here, if any.
Office.onReady();

function onNewMessageComposeHandler(event) {
    const item = Office.context.mailbox.item;
    const signatureIcon = "iVBORw0KGgoAAAANSUhEUgAAACcAAAAnCAMAAAC7faEHAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAzUExURQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAKMFRskAAAAQdFJOUwAQIDBAUGBwgI+fr7/P3+8jGoKKAAAACXBIWXMAAA7DAAAOwwHHb6hkAAABT0lEQVQ4T7XT2ZalIAwF0DAJhMH+/6+tJOQqot6X6joPiouNBo3w9/Hd6+hrYnUt6vhLcjEAJevVW0zJxABSlcunhERpjY+UKoNN5+ZgDGu2onNz0OngjP2FM1VdyBW1LtvGeYrBLs7U5I1PTXZt+zifcS3Icw2GcS3vxRY3Vn/iqx31hUyTnV515kdTfbaNhZLI30AceqDiIo4tyKEmJpKdP5M4um+nUwfDWxAXdzqMNKQ14jLdL5ntXzxcRF440mhS6yu882Kxa30RZcUIjTCJg7lscsR4VsMjfX9Q0Vuv/Wd3YosD1J4LuSRtaL7bzXGN1wx2cytUdncDuhA3fu6HPTiCvpQUIjZ3sCcHVbvLtbNTHlysx2w9/s27m9gEb+7CTri6hR1wcTf2gVf3wBRe3CMbcHYvTODkXhnD0+178K/pZ9+n/C1ru/2HAPwAo7YM1X4+tLMAAAAASUVORK5CYII=";

    // Get the sender's account information.
    item.from.getAsync((result) => {
        if (result.status === Office.AsyncResultStatus.Failed) {
            console.log(result.error.message);
            event.completed();
            return;
        }

        // Create a signature based on the sender's information.
        const name = result.value.displayName;
        const options = { asyncContext: name, isInline: true };
        item.addFileAttachmentFromBase64Async(signatureIcon, "signatureIcon.png", options, (result) => {
            if (result.status === Office.AsyncResultStatus.Failed) {
                console.log(result.error.message);
                event.completed();
                return;
            }

            // Add the created signature to the message.
            const signature = "<img src='cid:signatureIcon.png'>" + result.asyncContext;
            item.body.setSignatureAsync(signature, { coercionType: Office.CoercionType.Html }, (result) => {
                if (result.status === Office.AsyncResultStatus.Failed) {
                    console.log(result.error.message);
                    event.completed();
                    return;
                }

                // Show a notification when the signature is added to the message.
                // Important: Only the InformationalMessage type is supported in Outlook mobile at this time.
                const notification = {
                    type: Office.MailboxEnums.ItemNotificationMessageType.InformationalMessage,
                    message: "Company signature added.",
                    icon: "none",
                    persistent: false                        
                };
                item.notificationMessages.addAsync("signature_notification", notification, (result) => {
                    if (result.status === Office.AsyncResultStatus.Failed) {
                        console.log(result.error.message);
                        event.completed();
                        return;
                    }

                    event.completed();
                });
            });
        });
    });
}

  4. Save your changes.

Add a reference to the event-handling JavaScript file

Ensure that the ./src/commands/commands.html file has a reference to the JavaScript file that contains your event handler.

  1. Navigate to the ./src/commands folder, then open commands.html.

  2. Immediately before the closing head tag (</head>), add a script entry for the JavaScript file that contains the event handler.

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

  3. Save you changes.

Test and validate your add-in

  1. Follow the guidance to test and validate your add-in.

  2. Sideload your add-in in Outlook on Windows (classic or new (preview)), on Mac, or on the web.

  3. Open Outlook on Android or on iOS. If you have Outlook already open on your device, restart it.

  4. Create a new message. The event-based add-in adds the signature to the message. If you have a signature saved on your mobile device, it will briefly appear in the message you create, but will be immediately replaced by the signature added by the add-in.

    A sample signature added to a message being composed in Outlook mobile.

Behavior and limitations

As you develop an event-based add-in for Outlook mobile, be mindful of the following feature behaviors and limitations.

  • Only the OnNewMessageCompose event is supported on Outlook mobile at this time. This event occurs when a new message (including reply, reply all, and forward) is created. The OnNewMessageCompose event doesn't occur when you edit an existing draft.
  • Because event-based add-ins are expected to be short-running and lightweight, an add-in is allowed to run for a maximum of 60 seconds from the time it activates. To signal that your add-in has completed processing an event, your event handler must call the event.completed method. The add-in operation also ends when the user closes the compose window or sends the message.
  • Only one add-in can run at a time. If multiple event-based add-ins are installed on a user's account, they will run sequentially.
  • If you tap and hold the Outlook icon on your mobile device, then select New mail to create a new message, the event-based add-in may take a few seconds to initialize and complete processing the event.
  • If no changes are made to a new message being composed, a draft won't be saved, even if the event-based add-in adds a signature using the Office.context.mailbox.item.body.setSignatureAsync method.
  • In an event-based add-in that manages signatures, if you select Reply from the bottom of a message, the add-in activates and adds the signature to the message. However, the signature won't be visible in the current view. To view your message with the added signature, expand the compose window to full screen.
  • To enhance your add-in's functionality, you can use supported APIs from later requirement sets in compose mode. For more information, see Additional supported APIs.

Additional supported APIs

Although Outlook mobile supports APIs up to Mailbox requirement set 1.5, to further extend the capability of your event-based add-in in Outlook mobile, additional APIs from later requirement sets are now supported in compose mode.

To learn more about APIs that are supported in Outlook on mobile devices, see Outlook JavaScript APIs supported in Outlook on mobile devices.

Deploy to users

Event-based add-ins must be deployed by an organization's administrator. For guidance on how to deploy your add-in via the Microsoft 365 admin center, see the "Deploy to users" section of Configure your Outlook add-in for event-based activation.

See also