Create an encryption Outlook add-in

Implement custom encryption and decryption functionality in an Outlook add-in to secure email communications. The OnMessageDecrypt 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.

Try out a completed add-in

To immediately see a completed encryption add-in in action, try out the Encrypt and decrypt messages in Outlook sample.

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 OnMessageDecrypt event to conveniently determine when your add-in can decrypt a message and display the decrypted contents. To implement the OnMessageDecrypt event, you must:

1. Configure the add-in's manifest.
2. Implement event handling.

Supported environments

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

Configure the manifest

<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. This is used by Outlook on the web and the new Outlook on Windows. -->
          <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="OnMessageDecrypt" FunctionName="onMessageDecryptHandler" 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 OnMessageDecrypt 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 OnMessageDecrypt 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 OnMessageDecrypt 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 OnMessageDecrypt event handler.

function onMessageDecryptHandler(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 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.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("onMessageDecryptHandler", onMessageDecryptHandler);

Decrypt Outlook item attachments (preview)

Support for decrypting Outlook item attachments (Office.MailboxEnums.AttachmentType.Item), particularly email attachments, is available for preview in Outlook on the web and on Windows (new and classic). To preview this feature in classic Outlook on Windows, you must install Version 2606 (Build 20114.15110) or later. Then, join the Microsoft 365 Insider program and select the Beta Channel option to access Office beta builds. To test this feature using the sample code in this article, update the onMessageDecryptHandler function with the following code.

    // Decrypted content and properties of an email attachment.
    const decryptedEmailFile = "VGhpcyBpcyBhIHRleHQgZmlsZS4=...";
    const emailFileName = "Fabrikam_Report_202508.eml";

    const decryptedAttachments = [
        ...
        {
            attachmentType: Office.MailboxEnums.AttachmentType.Item,
            content: decryptedEmailFile,
            name: emailFileName
        }
    ];
    ...

Customize error messages for the decryption operation (preview)

Custom error messages for failed decryption operations are available for preview in Outlook on the web and on Windows (new and classic). To preview this feature in classic Outlook on Windows, you must install Version 2606 (Build 20114.15110) or later. Then, join the Microsoft 365 Insider program and select the Beta Channel option to access Office beta builds.

If the decryption operation fails, the allowEvent property of the event.completed call is set to false, and Outlook shows the following default notification to the user: "<Add-in name> failed to process your message." To specify a custom error message, set the errorMessage property of your add-in's event.completed call. Your custom message is prefixed with "Error from <add-in name>:". If your custom message can't be shown, the default notification is shown instead.

The following code sample shows how to specify a custom error message for your decryption add-in.

event.completed({
    allowEvent: false,
    errorMessage: "This message couldn't be decrypted. Contact the Contoso IT team for further assistance."
});

Manage distribution of decrypted content (preview)

To help prevent unauthorized distribution of decrypted content, access control options are available for preview in Outlook on the web and on Windows (new and classic). To preview this feature in classic Outlook on Windows, you must install Version 2606 (Build 20114.15110) or later. Then, join the Microsoft 365 Insider program and select the Beta Channel option to access Office beta builds.

To limit printing, copying, or saving of decrypted content, include the accessControls property of the event.completed call. Then, set the allowPrint, allowCopyPaste, and allowSave properties to false. If the accessControls property isn't specified, access controls default to true.

To test this feature using the sample code in this article, update the event.completed call of the onMessageDecryptHandler function with the following code.

    event.completed({
        allowEvent: true,
        emailBody: decryptedBody,
        attachments: decryptedAttachments,
        contextData: { messageType: "ReplyFromDecryptedMessage" },
        accessControls: {
            allowPrint: false,
            allowCopyPaste: false,
            allowSave: false
        }
    });

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 alerts them that the message is encrypted. 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.

• The attachments property of the event.completed method doesn't support attachments of type Office.MailboxEnums.AttachmentType.Item, except for preview in Outlook on the web and on Windows (new and classic). To learn more, see Decrypt Outlook item attachments (preview).

• Custom encryption add-ins can't encrypt messages that are already protected by DRM or S/MIME.

• In Outlook on the web and the new Outlook on Windows, when encrypted messages are grouped by conversation, only the currently selected message from the conversation thread is decrypted. The other messages in the conversation thread remain encrypted until they're selected.

• In Outlook on the web and the new Outlook on Windows, users can only download a decrypted message in the EML format. The option to download in the MSG format is unavailable.

Decryption notifications

Add-ins that handle the OnMessageDecrypt event automatically display notifications in certain decryption scenarios as described in the following table.

See also

• Sample: Encrypt and decrypt messages in Outlook
• 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