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.

Overview of the encryption and decryption workflows

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.

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.
2. Implement event handling.

Supported environments

The OnMessageRead event is supported on the Message Read surface. Support varies by client and Exchange environment, as shown in the following table.

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, 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 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.

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

   

Configure the manifest

To activate your add-in on the OnMessageRead event, you must configure the <VersionOverridesV1_1> 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 <Override> child element of the <Runtime> element.
• Specify the OnMessageRead event in the Type attribute of a <LaunchEvent> 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 <VersionOverrides> node that implements the OnMessageRead event.

<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.15">
        <bt:Set Name="Mailbox"/>
      </bt:Sets>
    </Requirements>
    <Hosts>
      <Host xsi:type="MailHost">
        <Runtimes>
            <!-- References the HTML file that links to the event handler. -->
          <Runtime resid="WebViewRuntime.Url">
            <!-- References the JavaScript file that contains the event handler. This is used by classic Outlook on Windows. -->
            <Override type="javascript" resid="JSRuntime.Url"/>
          </Runtime>
        </Runtimes>
        <DesktopFormFactor>
          <FunctionFile resid="WebViewRuntime.Url"/>
          <!-- Implements event-based activation. -->
          <ExtensionPoint xsi:type="LaunchEvent">
            <LaunchEvents>
              <LaunchEvent Type="OnMessageSend" FunctionName="onMessageSendHandler" SendMode="SoftBlock"/>
              <LaunchEvent Type="OnMessageRead" FunctionName="onMessageReadHandler" HeaderName="contoso-encrypted"/>
            </LaunchEvents>
            <!-- Identifies the runtime to be used (also referenced by the Runtime element). -->
            <SourceLocation resid="WebViewRuntime.Url"/>
        </ExtensionPoint>
        </DesktopFormFactor>
      </Host>
    </Hosts>
    <Resources>
      ...
      <bt:Urls>
        <bt:Url id="WebViewRuntime.Url" DefaultValue="https://www.contoso.com/launchevent.html"/>
        <bt:Url id="JSRuntime.Url" DefaultValue="https://www.contoso.com/launchevent.js"/>
      </bt:Urls>
      ...
    </Resources>
  </VersionOverrides>
</VersionOverrides>

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 <LaunchEvent> 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 object to the event.completed call and set its allowEvent property to true. Then, specify the decrypted contents of the message in the object's emailBody and attachments properties. You can also specify any data that your add-in may need for processing in the contextData property. For example, you can store custom internet headers to decrypt messages in reply and forward scenarios.

The following is an example of an OnMessageRead event handler.

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 = "<p>Please find attached the recent report and its supporting documentation.</p>";
    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);

Behavior and limitations

• Be aware of the behaviors and limitations of event-based add-ins. To learn more, see Activate add-ins with events.

• 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.

  

• 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.

See also

• Privacy and security for Office Add-ins
• Activate add-ins with events
• Troubleshoot event-based and spam-reporting add-ins
• Get and set internet headers on a message in an Outlook add-in
• Manage the sensitivity label of your message or appointment in compose mode