diff --git a/docs/develop/event-based-activation.md b/docs/develop/event-based-activation.md index a09f5a459..fc7a3b9ad 100644 --- a/docs/develop/event-based-activation.md +++ b/docs/develop/event-based-activation.md @@ -1,7 +1,7 @@ --- title: Activate add-ins with events description: Learn how to develop an Office Add-in that implements event-based activation. -ms.date: 08/01/2025 +ms.date: 10/09/2025 ms.topic: concept-article ms.localizationpriority: medium --- @@ -54,24 +54,25 @@ Support for this feature in Outlook was introduced in [requirement set 1.10](/ja |Event canonical name
and add-in only 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](/javascript/api/requirement-sets/outlook/requirement-set-1.10/outlook-requirement-set-1.10)
| -|`OnNewAppointmentOrganizer`|newAppointmentOrganizerCreated|On creating a new appointment but not on editing an existing one.|[1.10](/javascript/api/requirement-sets/outlook/requirement-set-1.10/outlook-requirement-set-1.10)
| -|`OnMessageAttachmentsChanged`|messageAttachmentsChanged|On adding or removing attachments while composing a message.

Event-specific data object: [AttachmentsChangedEventArgs](/javascript/api/outlook/office.attachmentschangedeventargs?view=outlook-js-1.11&preserve-view=true)|[1.11](/javascript/api/requirement-sets/outlook/requirement-set-1.11/outlook-requirement-set-1.11)
| -|`OnAppointmentAttachmentsChanged`|appointmentAttachmentsChanged|On adding or removing attachments while composing an appointment.

Event-specific data object: [AttachmentsChangedEventArgs](/javascript/api/outlook/office.attachmentschangedeventargs?view=outlook-js-1.11&preserve-view=true)|[1.11](/javascript/api/requirement-sets/outlook/requirement-set-1.11/outlook-requirement-set-1.11)
| -|`OnMessageRecipientsChanged`|messageRecipientsChanged|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)|[1.11](/javascript/api/requirement-sets/outlook/requirement-set-1.11/outlook-requirement-set-1.11)
| -|`OnAppointmentAttendeesChanged`|appointmentAttendeesChanged|On adding or removing attendees while composing an appointment.

Event-specific data object: [RecipientsChangedEventArgs](/javascript/api/outlook/office.recipientschangedeventargs?view=outlook-js-1.11&preserve-view=true)|[1.11](/javascript/api/requirement-sets/outlook/requirement-set-1.11/outlook-requirement-set-1.11)
| -|`OnAppointmentTimeChanged`|appointmentTimeChanged|On changing date/time while composing an appointment.

Event-specific data object: [AppointmentTimeChangedEventArgs](/javascript/api/outlook/office.appointmenttimechangedeventargs?view=outlook-js-1.11&preserve-view=true)

**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](/javascript/api/requirement-sets/outlook/requirement-set-1.11/outlook-requirement-set-1.11)
| -|`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](/javascript/api/outlook/office.recurrencechangedeventargs?view=outlook-js-1.11&preserve-view=true)|[1.11](/javascript/api/requirement-sets/outlook/requirement-set-1.11/outlook-requirement-set-1.11)
| -|`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](/javascript/api/outlook/office.infobarclickedeventargs?view=outlook-js-1.11&preserve-view=true)|[1.11](/javascript/api/requirement-sets/outlook/requirement-set-1.11/outlook-requirement-set-1.11)
| -|`OnMessageSend`|messageSending|On sending a message item. To learn more, try the [Smart Alerts walkthrough](../outlook/smart-alerts-onmessagesend-walkthrough.md).|[1.12](/javascript/api/requirement-sets/outlook/requirement-set-1.12/outlook-requirement-set-1.12)
| -|`OnAppointmentSend`|appointmentSending|On sending an appointment item. To learn more, see [Handle OnMessageSend and OnAppointmentSend events in your Outlook add-in with Smart Alerts](../outlook/onmessagesend-onappointmentsend-events.md).|[1.12](/javascript/api/requirement-sets/outlook/requirement-set-1.12/outlook-requirement-set-1.12)
| -|`OnMessageCompose`|messageComposeOpened|On composing a new message (includes reply, reply all, and forward) or editing a draft.|[1.12](/javascript/api/requirement-sets/outlook/requirement-set-1.12/outlook-requirement-set-1.12)
| -|`OnAppointmentOrganizer`|appointmentOrganizerOpened|On creating a new appointment or editing an existing one.|[1.12](/javascript/api/requirement-sets/outlook/requirement-set-1.12/outlook-requirement-set-1.12)
| -|`OnMessageFromChanged`|messageFromChanged|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](../outlook/onmessagefromchanged-onappointmentfromchanged-events.md).|[1.13](/javascript/api/requirement-sets/outlook/requirement-set-1.13/outlook-requirement-set-1.13)
| -|`OnAppointmentFromChanged`|appointmentFromChanged|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](../outlook/onmessagefromchanged-onappointmentfromchanged-events.md).|[1.13](/javascript/api/requirement-sets/outlook/requirement-set-1.13/outlook-requirement-set-1.13)
| -|`OnSensitivityLabelChanged`|sensitivityLabelChanged|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](../outlook/sensitivity-label.md).

Event-specific data object: [SensitivityLabelChangedEventArgs](/javascript/api/outlook/office.sensitivitylabelchangedeventargs?view=outlook-js-preview&preserve-view=true)|[1.13](/javascript/api/requirement-sets/outlook/requirement-set-1.13/outlook-requirement-set-1.13)
| -|`OnMessageReadWithCustomAttachment`|Not available|On opening a message that contains a specific attachment type in read mode.|[Preview](/javascript/api/requirement-sets/outlook/preview-requirement-set/outlook-requirement-set-preview)5
| -|`OnMessageReadWithCustomHeader`|Not available|On opening a message that contains a specific internet header name in read mode.|[Preview](/javascript/api/requirement-sets/outlook/preview-requirement-set/outlook-requirement-set-preview)5
| +|`OnNewMessageCompose`| newMessageComposeCreated |On composing a new message (includes reply, reply all, and forward) but not on editing, for example, a draft.|[1.10](/javascript/api/requirement-sets/outlook/requirement-set-1.10/outlook-requirement-set-1.10)| +|`OnNewAppointmentOrganizer`|newAppointmentOrganizerCreated|On creating a new appointment but not on editing an existing one.|[1.10](/javascript/api/requirement-sets/outlook/requirement-set-1.10/outlook-requirement-set-1.10)| +|`OnMessageAttachmentsChanged`|messageAttachmentsChanged|On adding or removing attachments while composing a message.

Event-specific data object: [AttachmentsChangedEventArgs](/javascript/api/outlook/office.attachmentschangedeventargs?view=outlook-js-1.11&preserve-view=true)|[1.11](/javascript/api/requirement-sets/outlook/requirement-set-1.11/outlook-requirement-set-1.11)| +|`OnAppointmentAttachmentsChanged`|appointmentAttachmentsChanged|On adding or removing attachments while composing an appointment.

Event-specific data object: [AttachmentsChangedEventArgs](/javascript/api/outlook/office.attachmentschangedeventargs?view=outlook-js-1.11&preserve-view=true)|[1.11](/javascript/api/requirement-sets/outlook/requirement-set-1.11/outlook-requirement-set-1.11)| +|`OnMessageRecipientsChanged`|messageRecipientsChanged|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)|[1.11](/javascript/api/requirement-sets/outlook/requirement-set-1.11/outlook-requirement-set-1.11)| +|`OnAppointmentAttendeesChanged`|appointmentAttendeesChanged|On adding or removing attendees while composing an appointment.

Event-specific data object: [RecipientsChangedEventArgs](/javascript/api/outlook/office.recipientschangedeventargs?view=outlook-js-1.11&preserve-view=true)|[1.11](/javascript/api/requirement-sets/outlook/requirement-set-1.11/outlook-requirement-set-1.11)| +|`OnAppointmentTimeChanged`|appointmentTimeChanged|On changing date/time while composing an appointment.

Event-specific data object: [AppointmentTimeChangedEventArgs](/javascript/api/outlook/office.appointmenttimechangedeventargs?view=outlook-js-1.11&preserve-view=true)

**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](/javascript/api/requirement-sets/outlook/requirement-set-1.11/outlook-requirement-set-1.11)| +|`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](/javascript/api/outlook/office.recurrencechangedeventargs?view=outlook-js-1.11&preserve-view=true)|[1.11](/javascript/api/requirement-sets/outlook/requirement-set-1.11/outlook-requirement-set-1.11)| +|`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](/javascript/api/outlook/office.infobarclickedeventargs?view=outlook-js-1.11&preserve-view=true)|[1.11](/javascript/api/requirement-sets/outlook/requirement-set-1.11/outlook-requirement-set-1.11)| +|`OnMessageSend`|messageSending|On sending a message item. To learn more, try the [Smart Alerts walkthrough](../outlook/smart-alerts-onmessagesend-walkthrough.md).|[1.12](/javascript/api/requirement-sets/outlook/requirement-set-1.12/outlook-requirement-set-1.12)| +|`OnAppointmentSend`|appointmentSending|On sending an appointment item. To learn more, see [Handle OnMessageSend and OnAppointmentSend events in your Outlook add-in with Smart Alerts](../outlook/onmessagesend-onappointmentsend-events.md).|[1.12](/javascript/api/requirement-sets/outlook/requirement-set-1.12/outlook-requirement-set-1.12)| +|`OnMessageCompose`|messageComposeOpened|On composing a new message (includes reply, reply all, and forward) or editing a draft.|[1.12](/javascript/api/requirement-sets/outlook/requirement-set-1.12/outlook-requirement-set-1.12)| +|`OnAppointmentOrganizer`|appointmentOrganizerOpened|On creating a new appointment or editing an existing one.|[1.12](/javascript/api/requirement-sets/outlook/requirement-set-1.12/outlook-requirement-set-1.12)| +|`OnMessageFromChanged`|messageFromChanged|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](../outlook/onmessagefromchanged-onappointmentfromchanged-events.md).|[1.13](/javascript/api/requirement-sets/outlook/requirement-set-1.13/outlook-requirement-set-1.13)| +|`OnAppointmentFromChanged`|appointmentFromChanged|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](../outlook/onmessagefromchanged-onappointmentfromchanged-events.md).|[1.13](/javascript/api/requirement-sets/outlook/requirement-set-1.13/outlook-requirement-set-1.13)| +|`OnSensitivityLabelChanged`|sensitivityLabelChanged|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](../outlook/sensitivity-label.md).

Event-specific data object: [SensitivityLabelChangedEventArgs](/javascript/api/outlook/office.sensitivitylabelchangedeventargs?view=outlook-js-preview&preserve-view=true)|[1.13](/javascript/api/requirement-sets/outlook/requirement-set-1.13/outlook-requirement-set-1.13)| +|`OnMessageReadWithCustomAttachment`|Not available|On opening a message that contains a specific attachment type in read mode.|[Preview](/javascript/api/requirement-sets/outlook/preview-requirement-set/outlook-requirement-set-preview)5| +|`OnMessageReadWithCustomHeader`|Not available|On opening a message that contains a specific internet header name in read mode.|[Preview](/javascript/api/requirement-sets/outlook/preview-requirement-set/outlook-requirement-set-preview)5| +|`OnMessageRead` (preview)|Not available|On matching the header of an encrypted message to the header key in an add-in's manifest. To learn more, see [Create an encryption Outlook add-in](../outlook/encryption-decryption.md).|[Preview](/javascript/api/requirement-sets/outlook/preview-requirement-set/outlook-requirement-set-preview)| > [!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. diff --git a/docs/images/outlook-encryption-placeholder-message.png b/docs/images/outlook-encryption-placeholder-message.png new file mode 100644 index 000000000..3a9d7ff8e Binary files /dev/null and b/docs/images/outlook-encryption-placeholder-message.png differ diff --git a/docs/outlook/encryption-decryption.md b/docs/outlook/encryption-decryption.md new file mode 100644 index 000000000..89b60e04e --- /dev/null +++ b/docs/outlook/encryption-decryption.md @@ -0,0 +1,242 @@ +--- +title: Create an encryption Outlook add-in (preview) +description: Learn how to develop an Outlook add-in that encrypts and decrypts messages. +ms.date: 10/09/2025 +ms.topic: how-to +ms.localizationpriority: medium +--- + +# Create an encryption Outlook add-in (preview) + +Implement custom encryption and decryption functionality in an Outlook add-in to secure email communications. The `OnMessageRead` event lets your add-in automatically identify encrypted messages and handle decryption, content display, and error notifications. + +> [!NOTE] +> The `OnMessageRead` event and decryption APIs are in preview. Features in preview shouldn't be used in production add-ins as they may change based on feedback we receive. We invite you to try out this feature in test or development environments and welcome feedback on your experience through GitHub (see the "Office Add-ins feedback" section at the end of this page). + +## Overview of the encryption and decryption workflows + +> [!TIP] +> +> - The encryption and decryption workflows implement the event-based activation feature. If you aren't familiar with event-based activation in Outlook add-ins, we recommend that you first learn about the feature and its implementation. To learn more, see [Activate add-ins with events](../develop/event-based-activation.md). +> - The minimum requirement set and supported platforms may vary for each API recommended in this section. We recommend verifying any requirements against [Outlook JavaScript API requirement sets](/javascript/api/requirement-sets/outlook/outlook-api-requirement-sets#outlook-client-support) and supplementing it with documentation for the specific API. + +The following table provides an overview of the encryption and decryption workflows of an Outlook add-in. It also identifies whether a step requires a custom solution or is supported by the Office JavaScript (Office.js) API library. + +| Step | Implementation | +| ---- | -------------- | +| User composes a message and uses your add-in to apply encryption rules | You must implement your own encryption protocol so that the add-in can secure the contents of the message and its attachments. | +| User sends the message | Implement a handler for the [OnMessageSend](onmessagesend-onappointmentsend-events.md) event so that your add-in can automatically run your encryption protocol when the user selects **Send**.

To identify a message that was encrypted using your add-in during the decryption process, use the [internet headers APIs](/javascript/api/outlook/office.internetheaders) to add a header to a message. The header key must match the value specified in the `HeaderName` attribute of the [\](/javascript/api/manifest/launchevent?view=outlook-js-preview&preserve-view=true) element for the [OnMessageRead](../develop/event-based-activation.md#outlook-events) event in the add-in's manifest. For more information, see [Implement decryption using event-based activation](#implement-decryption-using-event-based-activation). | +| Recipient receives the encrypted message and opens it | If the recipient has the same add-in that was used to encrypt the message installed in Outlook, the add-in checks whether the header key included in the message matches the value specified for the `OnMessageRead` event in the manifest. This operation is automatically done by an add-in that handles the `OnMessageRead` event, so that you don't have to manually implement the check. If the headers match, the `OnMessageRead` event occurs and its handler runs. For more information, see [Implement decryption using event-based activation](#implement-decryption-using-event-based-activation). | +| Add-in decrypts the message | You must implement your own decryption protocol in the `OnMessageRead` event handler. While your add-in decrypts the message and its attachments, a notification is shown to the user to alert them that their message is being processed by the add-in. This notification is automatically shown by an add-in that handles the `OnMessageRead` event, so that you don't have to manually create one. | +| Recipient views the decrypted message and its attachments, if any | Once the decryption operation is complete, a notification is automatically shown to the user to alert them that the add-in has finished processing the message. In your `OnMessageRead` handler, call the [event.completed](/javascript/api/outlook/office.mailboxevent?view=outlook-js-preview&preserve-view=true#outlook-office-mailboxevent-completed-member(1)) method and pass it a [MessageDecryptEventCompletedOptions](/javascript/api/outlook/office.messagedecrypteventcompletedoptions?view=outlook-js-preview&preserve-view=true) object. With the `MessageDecryptEventCompletedOptions` object, you can specify whether to display the decrypted content to the recipient. For more information, see [Implement event handling](#implement-event-handling). | + +## Implement decryption using event-based activation + +You must implement your own encryption and decryption protocols. The add-in must also be configured to handle the `OnMessageRead` event to conveniently determine when your add-in can decrypt a message and display the decrypted contents. To implement the `OnMessageRead` event, you must: + +1. [Configure the add-in's manifest](#configure-the-manifest). +1. [Implement event handling](#implement-event-handling). + +### Supported environments + +The `OnMessageRead` event is supported on the [Message Read](read-scenario.md) surface. Support varies by client and Exchange environment, as shown in the following table. + +| Client | Exchange Online | Exchange Subscription Edition (SE) | Exchange Server 2019 | Exchange Server 2016 | +| ------ | --------------- | ---------------------------------- | -------------------- | -------------------- | +| **Web browser** | Not available | Not available | Not available | Not available | +| **Windows (new)** | Not available | Not available | Not available | Not available | +| **Windows (classic)**
Version 2510 (Build 19312.20000) and later | In preview | Not available | Not available | Not available | +| **Mac** | Not available | Not available | Not available | Not available | +| **Android** | Not available | Not available | Not available | Not available | +| **iOS** | Not available | Not available | Not available | Not available | + +#### Preview the decryption APIs in classic Outlook on Windows + +To preview the decryption APIs in classic Outlook on Windows, join the [Microsoft 365 Insider program](https://aka.ms/MSFT365InsiderProgram), then choose the Beta Channel in the Outlook client. Your client must be on Version 2510 (Build 19312.20000) or later. + +Classic 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](/javascript/api/requirement-sets/outlook/preview-requirement-set/outlook-requirement-set-preview) in your event handlers in classic 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. + +1. Create an entry named `EnableBetaAPIsInJavaScript` and set its value to `1`. + + :::image type="content" source="../images/outlook-beta-registry-key.png" alt-text="The `EnableBetaAPIsInJavaScript` key is set to 1 in the Registry Editor."::: + +### Configure the manifest + +> [!NOTE] +> The `OnMessageRead` event can currently only be implemented with an add-in only manifest. + +To activate your add-in on the `OnMessageRead` event, you must configure the [\](/javascript/api/manifest/versionoverrides-1-1-mail) node of your add-in's **manifest.xml** file as follows. + +- To run an event-based add-in in classic Outlook on Windows, you must specify the JavaScript file that contains the event handler in the [\](/javascript/api/manifest/override) child element of the [\](/javascript/api/manifest/runtime) element. +- Specify the `OnMessageRead` event in the `Type` attribute of a [\](/javascript/api/manifest/launchevent?view=outlook-js-preview&preserve-view=true) element. You must assign the function name of the event handler to the `FunctionName` attribute of the element. To facilitate checking whether the message was encrypted by the add-in, a header key must be specified in the `HeaderName` attribute. The same header is added to a message that's encrypted by the add-in. + +The following is an example of a `` node that implements the `OnMessageRead` event. + +```xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ... + + + + + ... + + + +``` + +### Implement event handling + +The `OnMessageRead` event handler is used to run the decryption operation and determine whether to display the decrypted contents of a message. + +- To ensure your handler runs when the `OnMessageRead` event occurs, call `Office.actions.associate` in the JavaScript file where the handler is implemented. This maps the handler name specified in the `FunctionName` attribute of the `` element in the manifest to its JavaScript counterpart. +- Once the decryption operation finishes, you must call `event.completed` to signal to the client that your add-in has completed processing the `OnMessageRead` event. To display the decrypted contents of a message and its attachments, pass a [MessageDecryptEventCompletedOptions](/javascript/api/outlook/office.messagedecrypteventcompletedoptions?view=outlook-js-preview&preserve-view=true) object to the `event.completed` call and set its [allowEvent](/javascript/api/outlook/office.messagedecrypteventcompletedoptions?view=outlook-js-preview&preserve-view=true#outlook-office-messagedecrypteventcompletedoptions-allowevent-member) property to `true`. Then, specify the decrypted contents of the message in the object's [emailBody](/javascript/api/outlook/office.messagedecrypteventcompletedoptions?view=outlook-js-preview&preserve-view=true#outlook-office-messagedecrypteventcompletedoptions-emailbody-member) and [attachments](/javascript/api/outlook/office.messagedecrypteventcompletedoptions?view=outlook-js-preview&preserve-view=true#outlook-office-messagedecrypteventcompletedoptions-attachments-member) properties. You can also specify any data that your add-in may need for processing in the [contextData](/javascript/api/outlook/office.messagedecrypteventcompletedoptions?view=outlook-js-preview&preserve-view=true#outlook-office-messagedecrypteventcompletedoptions-contextdata-member) property. For example, you can store custom internet headers to decrypt messages in reply and forward scenarios. + +> [!NOTE] +> Be mindful of the following when creating an event-based add-in for classic Outlook on Windows. +> +> - Imports aren't currently supported in the JavaScript file containing the event handler. +> - When the JavaScript function specified in the manifest to handle an event runs, code in `Office.onReady()` and `Office.initialize` isn't run. We recommend adding any startup logic needed by the event handler, such as checking the user's Outlook version, to the event handler instead. + +The following is an example of an `OnMessageRead` event handler. + +```javascript +function onMessageReadHandler(event) { + // Your code to decrypt the contents of a message would appear here. + ... + + // Use the results from your decryption process to display the decrypted contents of the message body and attachments. + const decryptedBodyContent = "

Please find attached the recent report and its supporting documentation.

"; + const decryptedBody = { + coercionType: Office.CoercionType.Html, + content: decryptedBodyContent + }; + + // Decrypted content and properties of a file attachment. + const decryptedPdfFile = "JVBERi0xLjQKJeLjz9MKNCAwIG9i..."; + const pdfFileName = "Fabrikam_Report_202509"; + + // Decrypted content and properties of a mail item. + const decryptedEmailFile = "VGhpcyBpcyBhIHRleHQgZmlsZS4=..."; + const emailFileName = "Fabrikam_Report_202508.eml"; + + // Decrypted properties of a cloud attachment. + const cloudFilePath = "https://contosostorage.com/reports/weekly_forecast.xlsx"; + const cloudFileName = "weekly_forecast.xlsx"; + + // Decrypted content and properties of an inline image. + const decryptedImageFile = "iVBORw0KGgoAAAANSUhEUgAA..."; + const imageFileName = "banner.png"; + const imageContentId = "image001.png@01DC1DD9.1A4AA300"; + + const decryptedAttachments = [ + { + attachmentType: Office.MailboxEnums.AttachmentType.File, + content: decryptedPdfFile, + isInline: false, + name: pdfFileName + }, + { + attachmentType: Office.MailboxEnums.AttachmentType.Item, + content: decryptedEmailFile, + isInline: false, + name: emailFileName + }, + { + attachmentType: Office.MailboxEnums.AttachmentType.Cloud, + isInline: false, + name: cloudFileName, + path: cloudFilePath + }, + { + attachmentType: Office.MailboxEnums.AttachmentType.File, + content: decryptedImageFile, + contentId: imageContentId, + isInline: true, + name: imageFileName + } + ]; + + event.completed({ + allowEvent: true, + emailBody: decryptedBody, + attachments: decryptedAttachments, + contextData: { messageType: "ReplyFromDecryptedMessage" } + }); +} + +// IMPORTANT: To ensure your add-in is supported in Outlook, remember to map the event handler name specified in the manifest to its JavaScript counterpart. +Office.actions.associate("onMessageReadHandler", onMessageReadHandler); +``` + +> [!TIP] +> In classic Outlook on Windows, when images are added to a message as inline attachments, they're automatically assigned a content ID. In the body of a message, the content ID of an inline attachment is specified in the `src` attribute of the `` element similar to the following example. +> +> `` +> +> To easily identify and provide these inline attachments during decryption, we recommend saving the content IDs of inline attachments to the message header during encryption. Call [Office.context.mailbox.item.getAttachmentsAsync](/javascript/api/outlook/office.messagecompose?view=outlook-js-preview&preserve-view=true#outlook-office-messagecompose-getattachmentsasync-member(1)) to get the [content ID](/javascript/api/outlook/office.attachmentdetailscompose?view=outlook-js-preview&preserve-view=true#outlook-office-attachmentdetailscompose-contentid-member) of an inline attachment. Then, call [Office.context.mailbox.item.internetHeaders.setAsync](/javascript/api/outlook/office.internetheaders#outlook-office-internetheaders-setasync-member(1)) to save the ID to the header of the message. + +## Behavior and limitations + +- Be aware of the behaviors and limitations of event-based add-ins. To learn more, see [Activate add-ins with events](../develop/event-based-activation.md#behavior-and-limitations). +- Since each add-in uses its own encryption protocol, a message can only be decrypted by the same add-in that encrypted it. When a user doesn't have the required add-in installed to decrypt a message, a notification isn't shown to them. To guide the user through the decryption process, customize a placeholder message for the body of the encrypted message. The placeholder message can include information on how to install your add-in. To set the message body during the encryption process, call [Office.context.mailbox.item.body.setAsync](/javascript/api/outlook/office.body#outlook-office-body-setasync-member(2)). + + :::image type="content" source="../images/outlook-encryption-placeholder-message.png" alt-text="A sample placeholder message of an encrypted message."::: + +- To ensure data security and confidentiality, decrypted content isn't stored on the Outlook client. The contents of an encrypted message are decrypted every time a user opens it. +- An encrypted message must first be decrypted before a user can reply or forward it. A user can't reply or forward an encrypted message while it's being decrypted. +- If a user navigates to another mail item while an encrypted message is being decrypted, the decryption process stops running. The user must select or open the message again to activate the decryption process. +- When replying to or forwarding encrypted messages, drafts are saved unencrypted in the **Drafts** folder. + +### Decryption notifications + +Add-ins that handle the `OnMessageRead` event automatically display notifications in certain decryption scenarios as described in the following table. + +| Notification | Scenario | +| ------------ | -------- | +| \ is unavailable and can't process your message at this time | Applies to classic Outlook on Windows only. This notification is shown when the add-in fails to load because an error prevented the add-in from loading or the user's client or machine is offline. | +| \ failed to process your message | An error was encountered while the add-in was decrypting the message. To retry the decryption operation, the recipient must switch to another message, then open the encrypted message again to invoke the `OnMessageRead` event. | +| \ is processing your message | The add-in is handling the `OnMessageRead` event to decrypt the message. | +| \ has finished processing your message | The add-in successfully decrypted the contents of the message. The user can now view the message and its attachments. | +| \ is taking longer than expected to process your message | The add-in has been running for more than five seconds, but less than five minutes. | +| \ timed out. To retry, select another email and then return to this message | The add-in times out after running for five minutes. To retry the decryption operation, the recipient must switch to another message, then open the encrypted message again to invoke the `OnMessageRead` event. | + +## See also + +- [Privacy and security for Office Add-ins](../concepts/privacy-and-security.md) +- [Activate add-ins with events](../develop/event-based-activation.md) +- [Troubleshoot event-based and spam-reporting add-ins](../testing/troubleshoot-event-based-and-spam-reporting-add-ins.md) +- [Get and set internet headers on a message in an Outlook add-in](internet-headers.md) +- [Manage the sensitivity label of your message or appointment in compose mode](sensitivity-label.md) diff --git a/docs/outlook/one-outlook.md b/docs/outlook/one-outlook.md index 308cbc11b..0fb8ae112 100644 --- a/docs/outlook/one-outlook.md +++ b/docs/outlook/one-outlook.md @@ -1,7 +1,7 @@ --- title: Develop Outlook add-ins for the new Outlook on Windows description: Learn how to develop add-ins that are compatible with the new Outlook on Windows. -ms.date: 08/05/2025 +ms.date: 10/09/2025 ms.localizationpriority: medium --- @@ -45,7 +45,7 @@ The following table identifies key Outlook scenarios and their support status in |Mail item transformation|Enable users to transform mail items into other formats.|Supported.|
  • [Drag and drop messages and attachments into the task pane of an Outlook add-in](drag-drop-items.md)
  • [getAsFileAsync method](/javascript/api/outlook/office.messageread#outlook-office-messageread-getasfileasync-member(1))
| |Project management|Enable users to create and track project work items from partner systems.|Supported.|
  • [Activate your Outlook add-in on multiple messages](item-multi-select.md)
  • [Activate your Outlook add-in without the Reading Pane enabled or a message selected](contextless.md)
  • [Verify the color categories applied to a new message or appointment](https://github.com/OfficeDev/Office-Add-in-samples/tree/main/Samples/outlook-check-item-categories)
| |Attachment management|Enable users to import or export attachments from partner locations.|Supported.|
  • [Activate your Outlook add-in on multiple messages](item-multi-select.md)
  • [Activate your Outlook add-in without the Reading Pane enabled or a message selected](contextless.md)
  • [Activate add-ins with events](../develop/event-based-activation.md)
  • [Drag and drop messages and attachments into the task pane of an Outlook add-in](drag-drop-items.md)
| -|Message encryption|Enable users to encrypt and decrypt messages.|Partially supported. Essential features are yet to be addressed to create a similar experience to VSTO or COM add-ins.|
  • [Office.context.mailbox.item.body.getAsync](/javascript/api/outlook/office.body#outlook-office-body-getasync-member(1))
  • [Office.context.mailbox.item.body.setAsync](/javascript/api/outlook/office.body#outlook-office-body-setasync-member(1))
  • [Office.context.mailbox.item.display](/javascript/api/outlook/office.messageread?view=outlook-js-preview&preserve-view=true#outlook-office-messageread-display-member) (preview)
  • [Office.context.mailbox.item.display.body.setAsync](/javascript/api/outlook/office.displayedbody?view=outlook-js-preview&preserve-view=true#outlook-office-displayedbody-setasync-member(1)) (preview)
  • [Office.context.mailbox.item.display.subject.setAsync](/javascript/api/outlook/office.displayedsubject#outlook-office-displayedsubject-setasync-member(1)) (preview)
| +|Message encryption|Enable users to encrypt and decrypt messages.|Partially supported. Essential features are yet to be addressed to create a similar experience to VSTO or COM add-ins.|
  • [Activate add-ins with events](../develop/event-based-activation.md)
  • [Handle OnMessageSend and OnAppointmentSend events in your Outlook add-in with Smart Alerts](onmessagesend-onappointmentsend-events.md)
  • [Create an encryption Outlook add-in](encryption-decryption.md)
  • [Office.MessageDecryptEventCompletedOptions](/javascript/api/outlook/office.messagedecrypteventcompletedoptions?view=outlook-js-preview&preserve-view=true) (preview)
  • [Office.DecryptedMessageAttachment](/javascript/api/outlook/office.decryptedmessageattachment?view=outlook-js-preview&preserve-view=true) (preview)
  • [Office.DecryptedMessageBody](/javascript/api/outlook/office.decryptedmessagebody?view=outlook-js-preview&preserve-view=true) (preview)
  • [Office.context.mailbox.item.body.getAsync](/javascript/api/outlook/office.body#outlook-office-body-getasync-member(1))
  • [Office.context.mailbox.item.body.setAsync](/javascript/api/outlook/office.body#outlook-office-body-setasync-member(1))
  • [Office.context.mailbox.item.display](/javascript/api/outlook/office.messageread?view=outlook-js-preview&preserve-view=true#outlook-office-messageread-display-member) (preview)
  • [Office.context.mailbox.item.display.body.setAsync](/javascript/api/outlook/office.displayedbody?view=outlook-js-preview&preserve-view=true#outlook-office-displayedbody-setasync-member(1)) (preview)
  • [Office.context.mailbox.item.display.subject.setAsync](/javascript/api/outlook/office.displayedsubject#outlook-office-displayedsubject-setasync-member(1)) (preview)
  • [Office.context.mailbox.item.internetHeaders.setAsync](/javascript/api/outlook/office.internetheaders#outlook-office-internetheaders-setasync-member(1))
| |Data loss prevention|Prevent users from forwarding mail items that contain highly sensitive information.|Supported.|
  • [Automatically check for an attachment before a message is sent](smart-alerts-onmessagesend-walkthrough.md)
  • [Handle OnMessageSend and OnAppointmentSend events in your Outlook add-in with Smart Alerts](onmessagesend-onappointmentsend-events.md)
  • [Manage the sensitivity label of your message or appointment in compose mode](sensitivity-label.md)
  • [Verify the sensitivity label of a message](https://github.com/OfficeDev/Office-Add-in-samples/tree/main/Samples/outlook-verify-sensitivity-label)
  • [Office.SensitivityLabel](/javascript/api/outlook/office.sensitivitylabelscatalog)
  • [Office.SensitivityLabelsCatalog](/javascript/api/outlook/office.sensitivitylabelscatalog)
  • [Office.SensitivityLabelDetails](/javascript/api/outlook/office.sensitivitylabeldetails)
  • [Office.context.mailbox.item.body.getAsync](/javascript/api/outlook/office.body#outlook-office-body-getasync-member(1))
  • [Office.context.mailbox.item.body.setAsync](/javascript/api/outlook/office.body#outlook-office-body-setasync-member(1))
  • [Office.context.mailbox.item.closeAsync](/javascript/api/outlook/office.messagecompose#outlook-office-messagecompose-closeasync-member(1))
  • [Office.context.mailbox.item.inReplyTo](/javascript/api/outlook/office.messagecompose#outlook-office-messagecompose-inreplyto-member)
  • [Office.context.mailbox.item.getConversationIndexAsync](/javascript/api/outlook/office.messagecompose#outlook-office-messagecompose-getconversationindexasync-member(1))
  • [Office.context.mailbox.item.getItemClassAsync](/javascript/api/outlook/office.messagecompose#outlook-office-messagecompose-getitemclassasync-member(1))
| |Mail item classification|Enable users to identify and classify messages that contain sensitive information.|Partially supported. Essential features are yet to be addressed to create a similar experience to VSTO or COM add-ins.|
  • [Automatically check for an attachment before a message is sent](smart-alerts-onmessagesend-walkthrough.md)
  • [Handle OnMessageSend and OnAppointmentSend events in your Outlook add-in with Smart Alerts](onmessagesend-onappointmentsend-events.md)
  • [Manage the sensitivity label of your message or appointment in compose mode](sensitivity-label.md)
  • [Manage the sensitivity level of an appointment](/javascript/api/outlook/office.sensitivity)
  • [Office.Sensitivity](/javascript/api/outlook/office.sensitivity)
  • [Office.SensitivityLabel](/javascript/api/outlook/office.sensitivitylabelscatalog)
  • [Office.SensitivityLabelsCatalog](/javascript/api/outlook/office.sensitivitylabelscatalog)
  • [Office.SensitivityLabelDetails](/javascript/api/outlook/office.sensitivitylabeldetails)
| |Data sync service|Enable bidirectional synchronization of mail items with partner systems.|Partially supported. Essential features are yet to be addressed to create a similar experience to VSTO or COM add-ins.|
  • [Use Microsoft Graph to manage personal contacts in Outlook](/graph/outlook-contacts-concept-overview)
| diff --git a/docs/toc.yml b/docs/toc.yml index 1356f4dc9..6a369d2b9 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -808,6 +808,9 @@ items: - name: Update your signature when switching between accounts href: outlook/onmessagefromchanged-onappointmentfromchanged-events.md displayName: event-based activation + - name: Create an encryption add-in + href: outlook/encryption-decryption.md + displayName: preview - name: Implement a spam reporting add-in href: outlook/spam-reporting.md - name: Activate add-in without Reading Pane or selected message