diff --git a/docs/outlook/autolaunch.md b/docs/outlook/autolaunch.md index 29d42ac2f..927c4b5a2 100644 --- a/docs/outlook/autolaunch.md +++ b/docs/outlook/autolaunch.md @@ -1,7 +1,7 @@ --- title: Configure your Outlook add-in for event-based activation description: Learn how to configure your Outlook add-in for event-based activation. -ms.date: 06/05/2025 +ms.date: 06/12/2025 ms.topic: concept-article ms.localizationpriority: medium --- @@ -12,8 +12,6 @@ The event-based activation feature lets a user use your add-in to complete their > [!NOTE] > Support for this feature was introduced in [requirement set 1.10](/javascript/api/requirement-sets/outlook/requirement-set-1.10/outlook-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](#supported-events) and [Requirement sets supported by Exchange servers and Outlook clients](/javascript/api/requirement-sets/outlook/outlook-api-requirement-sets#requirement-sets-supported-by-exchange-servers-and-outlook-clients). -> -> 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](mobile-event-based.md). ## Supported events @@ -43,10 +41,14 @@ The following table lists events that are currently available and the supported > [!NOTE] > 1 Event-based add-ins in classic 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](mobile-event-based.md). +> 2 For more information, see [Implement event-based activation in Outlook mobile add-ins](mobile-event-based.md). > > 3 To preview the `OnMessageReadWithCustomAttachment` and `OnMessageReadWithCustomHeader` events, you must install classic Outlook on Windows Version 2312 (Build 17110.10000) or later. Then, join the [Microsoft 365 Insider program](https://techcommunity.microsoft.com/blog/microsoft365insiderblog/join-the-microsoft-365-insider-program-on-windows/4206638) and select the **Beta Channel** option to access Office beta builds. +## Event-based activation in Outlook on mobile devices + +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](mobile-event-based.md). + ## Troubleshoot your add-in 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. For guidance on how to troubleshoot an event-based add-in, see [Troubleshoot event-based and spam-reporting add-ins](troubleshoot-event-based-and-spam-reporting-add-ins.md). @@ -133,18 +135,22 @@ Be aware that you must use additional security measures when using XMLHttpReques To make CORS requests from your event-based add-in, you must add the add-in and its JavaScript file to a well-known URI. For guidance on how to configure this resource, see [Use single sign-on (SSO) or cross-origin resource sharing (CORS) in your event-based or spam-reporting Outlook add-in](use-sso-in-event-based-activation.md). +## Try out event-based activation + +Discover how to streamline workflows and improve user experiences with event-based activation. Try out the samples to see the feature in action. + +- [Automatically set the subject of a new message or appointment](on-new-compose-events-walkthrough.md) +- [Automatically check for an attachment before a message is sent](smart-alerts-onmessagesend-walkthrough.md) +- [Automatically update your signature when switching between mail accounts](onmessagefromchanged-onappointmentfromchanged-events.md) +- [Encrypt attachments, process meeting request attendees, and react to appointment date/time changes using Outlook event-based activation](https://github.com/OfficeDev/Office-Add-in-samples/tree/main/Samples/outlook-encrypt-attachments) +- [Set your signature using Outlook event-based activation](https://github.com/OfficeDev/Office-Add-in-samples/tree/main/Samples/outlook-set-signature) +- [Identify and tag external recipients using Outlook event-based activation](https://github.com/OfficeDev/Office-Add-in-samples/tree/main/Samples/outlook-tag-external) +- [Verify the color categories of a message or appointment before it's sent using Smart Alerts](https://github.com/OfficeDev/Office-Add-in-samples/tree/main/Samples/outlook-check-item-categories) +- [Verify the sensitivity label of a message](https://github.com/OfficeDev/Office-Add-in-samples/tree/main/Samples/outlook-verify-sensitivity-label) + ## See also - [Troubleshoot event-based and spam-reporting add-ins](troubleshoot-event-based-and-spam-reporting-add-ins.md) - [Debug event-based and spam-reporting add-ins](debug-autolaunch.md) - [AppSource listing options for your event-based Outlook add-in](autolaunch-store-options.md) - [Handle OnMessageSend and OnAppointmentSend events in your Outlook add-in with Smart Alerts](onmessagesend-onappointmentsend-events.md) -- [Automatically set the subject of a new message or appointment](on-new-compose-events-walkthrough.md) -- [Automatically check for an attachment before a message is sent](smart-alerts-onmessagesend-walkthrough.md) -- [Automatically update your signature when switching between mail accounts](onmessagefromchanged-onappointmentfromchanged-events.md) -- Office Add-ins code samples: - - [Encrypt attachments, process meeting request attendees, and react to appointment date/time changes using Outlook event-based activation](https://github.com/OfficeDev/Office-Add-in-samples/tree/main/Samples/outlook-encrypt-attachments) - - [Set your signature using Outlook event-based activation](https://github.com/OfficeDev/Office-Add-in-samples/tree/main/Samples/outlook-set-signature) - - [Identify and tag external recipients using Outlook event-based activation](https://github.com/OfficeDev/Office-Add-in-samples/tree/main/Samples/outlook-tag-external) - - [Verify the color categories of a message or appointment before it's sent using Smart Alerts](https://github.com/OfficeDev/Office-Add-in-samples/tree/main/Samples/outlook-check-item-categories) - - [Verify the sensitivity label of a message](https://github.com/OfficeDev/Office-Add-in-samples/tree/main/Samples/outlook-verify-sensitivity-label) diff --git a/docs/outlook/mobile-event-based.md b/docs/outlook/mobile-event-based.md index 7046f8cb6..7af3667e4 100644 --- a/docs/outlook/mobile-event-based.md +++ b/docs/outlook/mobile-event-based.md @@ -1,7 +1,7 @@ --- title: Implement event-based activation in Outlook mobile add-ins description: Learn how to develop an Outlook mobile add-in that implements event-based activation. -ms.date: 04/22/2025 +ms.date: 06/12/2025 ms.topic: how-to ms.localizationpriority: medium --- @@ -21,9 +21,9 @@ To learn how to implement an event-based add-in for Outlook on the web, on Windo | Event canonical name and add-in only manifest name | Unified app manifest for Microsoft 365 name | Description | Supported clients | | ----- | ----- | ----- | ----- | -| `OnNewMessageCompose` | newMessageComposeCreated | Occurs on composing a new message (includes reply, reply all, and forward), but not on editing a draft. | | -| `OnMessageRecipientsChanged` | messageRecipientsChanged | Occurs on adding or removing recipients while composing a message.

Event-specific data object: [RecipientsChangedEventArgs](/javascript/api/outlook/office.recipientschangedeventargs?view=outlook-js-1.11&preserve-view=true) | | -| `OnMessageFromChanged` | messageFromChanged | Occurs 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](onmessagefromchanged-onappointmentfromchanged-events.md). | | +| `OnNewMessageCompose` | newMessageComposeCreated | Occurs on composing a new message (includes reply, reply all, and forward), but not on editing a draft. | | +| `OnMessageRecipientsChanged` | messageRecipientsChanged | Occurs on adding or removing recipients while composing a message.

Event-specific data object: [RecipientsChangedEventArgs](/javascript/api/outlook/office.recipientschangedeventargs?view=outlook-js-1.11&preserve-view=true) | | +| `OnMessageFromChanged` | messageFromChanged | Occurs 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](onmessagefromchanged-onappointmentfromchanged-events.md). | | ## Set up your environment diff --git a/docs/outlook/on-new-compose-events-walkthrough.md b/docs/outlook/on-new-compose-events-walkthrough.md index 8216a3445..7b1d71e1b 100644 --- a/docs/outlook/on-new-compose-events-walkthrough.md +++ b/docs/outlook/on-new-compose-events-walkthrough.md @@ -1,7 +1,7 @@ --- title: Automatically set the subject of a new message or appointment description: Learn how to implement an event-based add-in that automatically sets the subject of a new message or appointment. -ms.date: 10/08/2024 +ms.date: 06/12/2025 ms.topic: how-to ms.localizationpriority: medium --- @@ -13,7 +13,9 @@ Need to add a required disclaimer to all your messages? With an event-based add- The following sections teach you how to develop an add-in that handles the `OnNewMessageCompose` and `OnNewAppointmentOrganizer` events. By the end of this walkthrough, you'll have an add-in that automatically sets the subject of new messages and appointments being created. > [!NOTE] -> The `OnNewMessageCompose` and `OnNewAppointmentOrganizer` events were introduced in [requirement set 1.10](/javascript/api/requirement-sets/outlook/requirement-set-1.10/outlook-requirement-set-1.10). To verify that your Outlook client supports these events, see [Requirement sets supported by Exchange servers and Outlook clients](/javascript/api/requirement-sets/outlook/outlook-api-requirement-sets#requirement-sets-supported-by-exchange-servers-and-outlook-clients). +> +> - The `OnNewMessageCompose` and `OnNewAppointmentOrganizer` events were introduced in [requirement set 1.10](/javascript/api/requirement-sets/outlook/requirement-set-1.10/outlook-requirement-set-1.10). To verify that your Outlook client supports these events, see [Requirement sets supported by Exchange servers and Outlook clients](/javascript/api/requirement-sets/outlook/outlook-api-requirement-sets#requirement-sets-supported-by-exchange-servers-and-outlook-clients). +> - The `OnNewMessageCompose` event is now supported in Outlook on mobile devices. To learn how to implement this event in your Outlook mobile add-in, see [Implement event-based activation in Outlook mobile add-ins](mobile-event-based.md). ## Set up your environment @@ -288,7 +290,11 @@ In event-based add-ins, classic Outlook on Windows uses a JavaScript file, while 1. Save your changes. > [!NOTE] -> There are some limitations you must be aware of when developing an event-based add-in for classic Outlook on Windows. To learn more, see [Event-based activation behavior and limitations](autolaunch.md#event-based-activation-behavior-and-limitations). +> +> - There are some limitations you must be aware of when developing an event-based add-in for classic Outlook on Windows. To learn more, see [Event-based activation behavior and limitations](autolaunch.md#event-based-activation-behavior-and-limitations). +> - To ensure your add-in runs as expected when an event occurs, call `Office.actions.associate` in the JavaScript file where your handlers are implemented. This maps the event handler name specified in the manifest to its JavaScript counterpart. The location of the handler name in the manifest differs depending on the type of manifest your add-in uses. +> - **Unified manifest for Microsoft 365**: The value specified in the [`"actionId"`](/microsoft-365/extensibility/schema/extension-auto-run-events-array-events#actionid) property of the applicable [`"autoRunEvents.events"`](/microsoft-365/extensibility/schema/extension-auto-run-events-array-events) object. +> - **Add-in only manifest**: The function name specified in the applicable [LaunchEvent](/javascript/api/manifest/extensionpoint#launchevent) element. ## Update the commands HTML file diff --git a/docs/outlook/onmessagefromchanged-onappointmentfromchanged-events.md b/docs/outlook/onmessagefromchanged-onappointmentfromchanged-events.md index 930310a53..4727d57cb 100644 --- a/docs/outlook/onmessagefromchanged-onappointmentfromchanged-events.md +++ b/docs/outlook/onmessagefromchanged-onappointmentfromchanged-events.md @@ -1,7 +1,7 @@ --- title: Automatically update your signature when switching between Exchange accounts description: Learn how to automatically update your signature when switching between Exchange accounts through the OnMessageFromChanged and OnAppointmentFromChanged events in your event-based activation Outlook add-in. -ms.date: 03/11/2025 +ms.date: 06/12/2025 ms.topic: how-to ms.localizationpriority: medium --- @@ -372,18 +372,18 @@ Event handlers must be configured for the `OnNewMessageCompose` and `OnMessageFr } // IMPORTANT: To ensure your add-in is supported in Outlook, remember to - // map the event handler name specified in the manifest's LaunchEvent element (with the add-in only manifest) - // or the "autoRunEvents.events.actionId" property (with the unified manifest for Microsoft 365) - // to its JavaScript counterpart. + // map the event handler name specified in the manifest to its JavaScript counterpart. Office.actions.associate("onNewMessageComposeHandler", onNewMessageComposeHandler); Office.actions.associate("onMessageFromChangedHandler", onMessageFromChangedHandler); ``` > [!IMPORTANT] -> Windows: At present, imports aren't supported in the JavaScript file where you implement the handling for event-based activation. - -> [!TIP] -> Event-based add-ins running in classic Outlook on Windows don't run code included in the `Office.onReady()` and `Office.initialize` functions. We recommend adding your add-in startup logic, such as checking the user's Outlook version, to your event handlers instead. +> +> - In classic Outlook on Windows, imports aren't supported in the JavaScript file where you implement the handling for event-based activation. +> - Event-based add-ins running in classic Outlook on Windows don't run code included in the `Office.onReady()` and `Office.initialize` functions. We recommend adding your add-in startup logic, such as checking the user's Outlook version, to your event handlers instead. +> - To ensure your add-in runs as expected when an event occurs, call `Office.actions.associate` in the JavaScript file where your handlers are implemented. This maps the event handler name specified in the manifest to its JavaScript counterpart. The location of the handler name in the manifest differs depending on the type of manifest your add-in uses. +> - **Unified manifest for Microsoft 365**: The value specified in the [`"actionId"`](/microsoft-365/extensibility/schema/extension-auto-run-events-array-events#actionid) property of the applicable [`"autoRunEvents.events"`](/microsoft-365/extensibility/schema/extension-auto-run-events-array-events) object. +> - **Add-in only manifest**: The function name specified in the applicable [LaunchEvent](/javascript/api/manifest/extensionpoint#launchevent) element. ## Update the commands HTML file diff --git a/docs/outlook/outlook-mobile-apis.md b/docs/outlook/outlook-mobile-apis.md index a7c3833de..1735a2a26 100644 --- a/docs/outlook/outlook-mobile-apis.md +++ b/docs/outlook/outlook-mobile-apis.md @@ -1,7 +1,7 @@ --- title: Outlook JavaScript APIs supported in Outlook on mobile devices description: Learn which Outlook JavaScript APIs are supported in Outlook on mobile devices. -ms.date: 04/22/2025 +ms.date: 06/12/2025 ms.localizationpriority: medium --- @@ -29,6 +29,16 @@ The following table lists a subset of APIs from requirement sets beyond 1.5 that |[Office.context.mailbox.item.sessionData](/javascript/api/outlook/office.messagecompose#outlook-office-messagecompose-sessiondata-member)|Mailbox 1.11||| |[Office.AddinCommands.EventCompletedOptions](/javascript/api/office/office.addincommands.eventcompletedoptions)|Mailbox 1.8||| +## Supported events + +The following table lists the events that can be handled by add-ins running in Outlook on mobile devices. For more information about event-based activation, see [Implement event-based activation in Outlook mobile add-ins](mobile-event-based.md). + +|Event canonical name|Supported clients| +|---|---| +|`OnNewMessageCompose`|| +|`OnMessageRecipientsChanged`|| +|`OnMessageFromChanged`|| + ## Unsupported APIs Although Outlook mobile supports up to requirement set 1.5, there are some APIs from these earlier requirement sets that aren't supported. The following table lists these APIs and also notes features that aren't supported in certain Outlook modes. diff --git a/docs/outlook/smart-alerts-onmessagesend-walkthrough.md b/docs/outlook/smart-alerts-onmessagesend-walkthrough.md index 5a4b52ee4..2c8278528 100644 --- a/docs/outlook/smart-alerts-onmessagesend-walkthrough.md +++ b/docs/outlook/smart-alerts-onmessagesend-walkthrough.md @@ -1,7 +1,7 @@ --- title: Automatically check for an attachment before a message is sent description: Learn how to implement an event-based add-in that implements Smart Alerts to automatically check a message for an attachment before it's sent. -ms.date: 03/11/2025 +ms.date: 06/12/2025 ms.topic: how-to ms.localizationpriority: medium --- @@ -321,7 +321,9 @@ In this scenario, you'll add handling for sending a message. Your add-in will ch > [!IMPORTANT] > > - In classic Outlook on Windows, imports aren't currently supported in the JavaScript file where you implement the handling for event-based activation. -> - To ensure your add-in runs as expected when an `OnMessageSend` or `OnAppointmentSend` event occurs, call `Office.actions.associate` in the JavaScript file where your handlers are implemented. This maps the event handler name specified in the manifest to its JavaScript counterpart. If this call isn't included in your JavaScript file and the send mode property of your manifest is set to **soft block** or isn't specified, your users will be blocked from sending messages or meetings. +> - To ensure your add-in runs as expected when an `OnMessageSend` or `OnAppointmentSend` event occurs, call `Office.actions.associate` in the JavaScript file where your handlers are implemented. This maps the event handler name specified in the manifest to its JavaScript counterpart. If this call isn't included in your JavaScript file and the send mode property of your manifest is set to **soft block** or isn't specified, your users will be blocked from sending messages or meetings. The location of the handler name in the manifest differs depending on the type of manifest your add-in uses. +> - **Unified manifest for Microsoft 365**: The value specified in the [`"actionId"`](/microsoft-365/extensibility/schema/extension-auto-run-events-array-events#actionid) property of the applicable [`"autoRunEvents.events"`](/microsoft-365/extensibility/schema/extension-auto-run-events-array-events) object. +> - **Add-in only manifest**: The function name specified in the applicable [LaunchEvent](/javascript/api/manifest/extensionpoint#launchevent) element. > - The [errorMessageMarkdown](/javascript/api/outlook/office.smartalertseventcompletedoptions#outlook-office-smartalertseventcompletedoptions-errormessagemarkdown-member) property was introduced in [requirement set 1.15](/javascript/api/requirement-sets/outlook/requirement-set-1.15/outlook-requirement-set-1.15). Learn more about its [supported clients and platforms](/javascript/api/requirement-sets/outlook/outlook-api-requirement-sets#outlook-client-support). ## Customize the text and functionality of a button in the dialog (optional) diff --git a/docs/toc.yml b/docs/toc.yml index 857f0f56a..b25ade38e 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -752,6 +752,9 @@ items: - name: Implement Smart Alerts to handle on-send events href: outlook/onmessagesend-onappointmentsend-events.md displayName: event-based activation + - name: Event-based activation in Outlook on mobile devices + href: outlook/mobile-event-based.md + displayName: event-based activation, mobile - name: Set the subject of a new mail item href: outlook/on-new-compose-events-walkthrough.md displayName: event-based activation