Outlook API Public Preview Announcement – April 2020

Office Add-ins team

What’s included in the preview?

APIs in the following functional areas are included (please see more details below).

  1. Signature APIs – A set of APIs that enables developers to implement admin-driven, cloud-enabled custom signatures on e-mails.
  2. Append on send – APIs that enable adding content on emails and calendar items after users press “Send” (for example, disclaimers or signatures).
  3. Additional calendar properties – Access to additional properties that reduce the need to call EWS, REST, or Graph calls.

How to use the preview APIs?

The preview is now available in Outlook on the web and Windows. In order to try the new APIs, you will need to:

  1. Install the latest Office (for Windows) Insiders Fast (builds 16.12718.20010+).
  2. Use the preview CDN for Office.js at: https://appsforoffice.microsoft.com/lib/beta/hosted/office.js
  3. Configure targeted release on your Microsoft 365 tenant for access to the preview bits in Outlook on the web.

Signature API

This is a very popular request for our team to enable cloud-based signature management and tries to deal with the following gaps.

  • Enable signature across Outlook clients (Windows/OWA/Mac/Mobile).
  • Enable enterprise-themed admin-controlled signatures where:
    • Enterprise themes are enabled, including images, logos, etc.
    • Many signature solutions in the market stamp them in the server, meaning end users can’t visualize the signature before the e-mail is sent. This feature can enable the insertion of signatures during compose. (In the near future, we will enable a complementary feature to add the signature upon composing a new email.)
    • Insert signature directly under a new email.
    • Override the native behavior to enable a consistent look and feel.
  • Enable enterprise customization and design options for the signatures.

In order to enable the above, we are exposing the following APIs.

1. getComposeTypeAsync: Allows checking the type of email compose – new mail, reply, or forward.  This will provide developers with the ability to deliver a distinct signature for each case.

function getComposeType() {
  // Get the compose type of the current item (mail only).
  Office.context.mailbox.item.getComposeTypeAsync(function(asyncResult) {
    if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
      console.log(
        "getComposeTypeAsync succeeded with composeType: " +
        asyncResult.value.composeType +
        " and coercionType: " +
        asyncResult.value.coercionType
      );
    } else {
      console.error(asyncResult.error);
    }
  });
}

2. isClientSignatureEnabledAsync: Checks whether the native Outlook signature is enabled.   This allows developers to verify if the user is currently using a native signature.

function isClientSignatureEnabled() {
  // Check if the client signature is currently enabled.
  Office.context.mailbox.item.isClientSignatureEnabledAsync(function(asyncResult) {
    if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
      console.log("isClientSignatureEnabledAsync succeeded with result: " + asyncResult.value);
    } else {
      console.error(asyncResult.error);
    }
  });
}

3. disableClientSignatureAsync: Disables the native Outlook signature. This API enables developers to override the native signature behavior.

function disableClientSignature() {
  // Disable the client signature.
  Office.context.mailbox.item.disableClientSignatureAsync(function(asyncResult) {
    if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
      console.log("disableClientSignatureAsync succeeded");
    } else {
      console.error(asyncResult.error);
    }
  });
}

4. setSignatureAsync: Replaces the native outlook signature and stamps the add-in defined signature.

Note: You can use:

  • The optional object to change the insertion formatting to HTML.
  • Maximum 30,000 characters.
function setSignature() {
  // Set the signature for the current item.
  var signature = “This is my signature”;
  console.log(`Setting signature to "${signature}".`);
  Office.context.mailbox.item.body.setSignatureAsync(signature,{coercionType:"html"}, function(asyncResult) {
    if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
      console.log("setSignatureAsync succeeded");
    } else {
      console.error(asyncResult.error);
    }
  });
}

Append on send

Appends on send the specified content to the end of the message or appointment body, after any signature.

If the user is running add-ins that implement the on-send feature using ItemSend in the manifest, append on send runs before on-send functionality.

Important: To use appendOnSendAsync, the AppendOnSend extended permission must be included in the ExtendedPermissions node of the manifest.

Note: To clear data from a previous appendOnSendAsync call, you can call it again with the data parameter set to null.

function appendOnSend() {
  Office.context.mailbox.item.body.appendOnSendAsync(
    "Disclaimer: This is Append On Send",
    function(result) {
      console.log(result);
    });
}

 

Feedback usabilla icon