Office.Body interface

Package:

outlook

The body object provides methods for adding and updating the content of the message or appointment. It is returned in the body property of the selected item.

Remarks

[ API set: Mailbox 1.1 ]

Known issue with HTML table border colors

Outlook on Windows: If you're setting various cell borders to different colors in an HTML table in Compose mode, a cell's borders may not reflect the expected color. For the known behavior, visit OfficeDev/office-js issue #1818.

Minimum permission level: read item

Applicable Outlook mode: Compose or Read

Methods

getTypeAsync(options, callback)	Gets a value that indicates whether the content is in HTML or text format.
getTypeAsync(callback)	Gets a value that indicates whether the content is in HTML or text format.
prependAsync(data, options, callback)	Adds the specified content to the beginning of the item body.
prependAsync(data, callback)	Adds the specified content to the beginning of the item body.
setSelectedDataAsync(data, options, callback)	Replaces the selection in the body with the specified text. The setSelectedDataAsync method inserts the specified string at the cursor location in the body of the item, or, if text is selected in the editor, it replaces the selected text. If the cursor was never in the body of the item, or if the body of the item lost focus in the UI, the string will be inserted at the top of the body content. After insertion, the cursor is placed at the end of the inserted content. When including links in HTML markup, you can disable online link preview by setting the id attribute on the anchor (<a>) to "LPNoLP" (see the Examples section for a sample). Recommended: Call getTypeAsync then pass the returned value to the options.coercionType parameter.
setSelectedDataAsync(data, callback)	Replaces the selection in the body with the specified text. The setSelectedDataAsync method inserts the specified string at the cursor location in the body of the item, or, if text is selected in the editor, it replaces the selected text. If the cursor was never in the body of the item, or if the body of the item lost focus in the UI, the string will be inserted at the top of the body content. After insertion, the cursor is placed at the end of the inserted content. When including links in HTML markup, you can disable online link preview by setting the id attribute on the anchor (<a>) to "LPNoLP" (see the Examples section for a sample). Recommended: Call getTypeAsync then pass the returned value to the options.coercionType parameter.

Method Details

getTypeAsync(options, callback)

Gets a value that indicates whether the content is in HTML or text format.

getTypeAsync(options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<Office.CoercionType>) => void): void;

Parameters

options

Office.AsyncContextOptions

An object literal that contains one or more of the following properties:- asyncContext: Developers can provide any object they wish to access in the callback function.

callback

(asyncResult: Office.AsyncResult<Office.CoercionType>) => void

Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type Office.AsyncResult. The content type is returned as one of the CoercionType values in the asyncResult.value property.

Returns

void

Remarks

[ API set: Mailbox 1.1 ]

Minimum permission level: read item

Applicable Outlook mode: Compose

Important: In Outlook on Android and on iOS, this method isn't supported in the Message Compose mode. Only the Appointment Organizer mode is supported. For more information on supported APIs in Outlook mobile, see Outlook JavaScript APIs supported in Outlook on mobile devices.

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/20-item-body/get-body-format.yaml

// Get the mail item's body format (plain text or HTML) and log it to the console.
Office.context.mailbox.item.body.getTypeAsync((asyncResult) => {
  if (asyncResult.status === Office.AsyncResultStatus.Failed) {
    console.log("Action failed with error: " + asyncResult.error.message);
    return;
  }

  console.log("Body format: " + asyncResult.value);
});

getTypeAsync(callback)

Gets a value that indicates whether the content is in HTML or text format.

getTypeAsync(callback?: (asyncResult: Office.AsyncResult<Office.CoercionType>) => void): void;

Parameters

callback

(asyncResult: Office.AsyncResult<Office.CoercionType>) => void

Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type Office.AsyncResult. The content type is returned as one of the CoercionType values in the asyncResult.value property.

Returns

void

Remarks

[ API set: Mailbox 1.1 ]

Minimum permission level: read item

Applicable Outlook mode: Compose

Important: In Outlook on Android and on iOS, this method isn't supported in the Message Compose mode. Only the Appointment Organizer mode is supported. For more information on supported APIs in Outlook mobile, see Outlook JavaScript APIs supported in Outlook on mobile devices.

prependAsync(data, options, callback)

Adds the specified content to the beginning of the item body.

prependAsync(data: string, options: Office.AsyncContextOptions & CoercionTypeOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameters

data

string

The string to be inserted at the beginning of the body. The string is limited to 1,000,000 characters.

options

Office.AsyncContextOptions & Office.CoercionTypeOptions

An object literal that contains one or more of the following properties:- asyncContext: Developers can provide any object they wish to access in the callback function. coercionType: The desired format for the body. The string in the data parameter will be converted to this format.

callback

(asyncResult: Office.AsyncResult<void>) => void

Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type Office.AsyncResult. Any errors encountered will be provided in the asyncResult.error property.

Returns

void

Remarks

[ API set: Mailbox 1.1 ]

Minimum permission level: read/write item

Applicable Outlook mode: Compose

Important:

• After the content is prepended, the position of the cursor depends on which client the add-in is running. In Outlook on the web and on Windows, the cursor position remains the same in the pre-existing content of the body. For example, if the cursor was positioned at the beginning of the body prior to the prependAsync call, it will appear between the prepended content and the pre-existing content of the body after the call. In Outlook on Mac, the cursor position isn't preserved. The cursor disappears after the prependAsync call and only reappears when the user selects something in the body of the mail item.

• When working with HTML-formatted bodies, it's important to note that the client may modify the value passed to prependAsync to make it render efficiently with its rendering engine. This means that the value returned from a subsequent call to the Body.getAsync method (introduced in Mailbox 1.3) won't necessarily contain the exact value that was passed in the previous prependAsync call.

• When including links in HTML markup, you can disable online link preview by setting the id attribute on the anchor (<a>) to "LPNoLP" (see the Examples section for a sample).

• In Outlook on Android and on iOS, this method isn't supported in the Message Compose mode. Only the Appointment Organizer mode is supported. For more information on supported APIs in Outlook mobile, see Outlook JavaScript APIs supported in Outlook on mobile devices.

Recommended: Call getTypeAsync, then pass the returned value to the options.coercionType parameter.

Errors:

• DataExceedsMaximumSize: The data parameter is longer than 1,000,000 characters.

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/20-item-body/prepend-text-to-item-body.yaml

/* This snippet adds text to the beginning of the message or appointment's body. 
  
  When prepending a link in HTML markup to the body, you can disable the online link preview by setting the anchor tag's id attribute to "LPNoLP". For example, '<a id="LPNoLP" href="http://www.contoso.com">Click here!</a>'.
*/
const text = $("#text-field").val();

// It's recommended to call getTypeAsync and pass its returned value to the options.coercionType parameter of the prependAsync call.
Office.context.mailbox.item.body.getTypeAsync((asyncResult) => {
  if (asyncResult.status === Office.AsyncResultStatus.Failed) {
    console.log("Action failed with error: " + asyncResult.error.message);
    return;
  }

  const bodyFormat = asyncResult.value;
  Office.context.mailbox.item.body.prependAsync(text, { coercionType: bodyFormat }, (asyncResult) => {
    if (asyncResult.status === Office.AsyncResultStatus.Failed) {
      console.log("Action failed with error: " + asyncResult.error.message);
      return;
    }

    console.log(`"${text}" prepended to the body.`);
  });
});

prependAsync(data, callback)

Adds the specified content to the beginning of the item body.

prependAsync(data: string, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameters

data

string

The string to be inserted at the beginning of the body. The string is limited to 1,000,000 characters.

callback

(asyncResult: Office.AsyncResult<void>) => void

Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type Office.AsyncResult. Any errors encountered will be provided in the asyncResult.error property.

Returns

void

Remarks

[ API set: Mailbox 1.1 ]

Minimum permission level: read/write item

Applicable Outlook mode: Compose

Important:

• After the content is prepended, the position of the cursor depends on which client the add-in is running. In Outlook on the web and on Windows, the cursor position remains the same in the pre-existing content of the body. For example, if the cursor was positioned at the beginning of the body prior to the prependAsync call, it will appear between the prepended content and the pre-existing content of the body after the call. In Outlook on Mac, the cursor position isn't preserved. The cursor disappears after the prependAsync call and only reappears when the user selects something in the body of the mail item.

• When working with HTML-formatted bodies, it's important to note that the client may modify the value passed to prependAsync to make it render efficiently with its rendering engine. This means that the value returned from a subsequent call to the Body.getAsync method (introduced in Mailbox 1.3) won't necessarily contain the exact value that was passed in the previous prependAsync call.

• When including links in HTML markup, you can disable online link preview by setting the id attribute on the anchor (<a>) to "LPNoLP" (see the Examples section for a sample).

• In Outlook on Android and on iOS, this method isn't supported in the Message Compose mode. Only the Appointment Organizer mode is supported. For more information on supported APIs in Outlook mobile, see Outlook JavaScript APIs supported in Outlook on mobile devices.

Recommended: Call getTypeAsync, then pass the returned value to the options.coercionType parameter.

Errors:

• DataExceedsMaximumSize: The data parameter is longer than 1,000,000 characters.

setSelectedDataAsync(data, options, callback)

Replaces the selection in the body with the specified text.

The setSelectedDataAsync method inserts the specified string at the cursor location in the body of the item, or, if text is selected in the editor, it replaces the selected text. If the cursor was never in the body of the item, or if the body of the item lost focus in the UI, the string will be inserted at the top of the body content. After insertion, the cursor is placed at the end of the inserted content.

When including links in HTML markup, you can disable online link preview by setting the id attribute on the anchor (<a>) to "LPNoLP" (see the Examples section for a sample).

Recommended: Call getTypeAsync then pass the returned value to the options.coercionType parameter.

setSelectedDataAsync(data: string, options: Office.AsyncContextOptions & CoercionTypeOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameters

data

string

The string that will replace the existing body. The string is limited to 1,000,000 characters.

options

Office.AsyncContextOptions & Office.CoercionTypeOptions

An object literal that contains one or more of the following properties:- asyncContext: Developers can provide any object they wish to access in the callback function. coercionType: The desired format for the body. The string in the data parameter will be converted to this format.

callback

(asyncResult: Office.AsyncResult<void>) => void

Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type Office.AsyncResult. Any errors encountered will be provided in the asyncResult.error property.

Returns

void

Remarks

[ API set: Mailbox 1.1 ]

Minimum permission level: read/write item

Applicable Outlook mode: Compose

Errors:

• DataExceedsMaximumSize: The data parameter is longer than 1,000,000 characters.

• InvalidFormatError: The options.coercionType parameter is set to Office.CoercionType.Html and the message body is in plain text.

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/20-item-body/replace-selected-text.yaml

/* This snippet replaces selected text in a message or appointment's body with specified text.
  
  If you want to use a link in HTML markup as a value of the setSelectedDataAsync call's data parameter, you can disable online link preview by setting the anchor tag's id attribute to "LPNoLP". For example, '<a id="LPNoLP" href="http://www.contoso.com">Click here!</a>'.
*/
const text = $("#text-field").val();

// It's recommended to call getTypeAsync and pass its returned value to the options.coercionType parameter of the prependAsync call.
Office.context.mailbox.item.body.getTypeAsync((asyncResult) => {
  if (asyncResult.status === Office.AsyncResultStatus.Failed) {
    console.log("Action failed with error: " + asyncResult.error.message);
    return;
  }

  const bodyFormat = asyncResult.value;
  Office.context.mailbox.item.body.setSelectedDataAsync(text, { coercionType: bodyFormat }, (asyncResult) => {
    if (asyncResult.status === Office.AsyncResultStatus.Failed) {
      console.log("Action failed with error: " + asyncResult.error.message);
      return;
    }

    console.log(`Replaced selected text with "${text}".`);
  });
});

setSelectedDataAsync(data, callback)

Replaces the selection in the body with the specified text.

The setSelectedDataAsync method inserts the specified string at the cursor location in the body of the item, or, if text is selected in the editor, it replaces the selected text. If the cursor was never in the body of the item, or if the body of the item lost focus in the UI, the string will be inserted at the top of the body content. After insertion, the cursor is placed at the end of the inserted content.

When including links in HTML markup, you can disable online link preview by setting the id attribute on the anchor (<a>) to "LPNoLP" (see the Examples section for a sample).

Recommended: Call getTypeAsync then pass the returned value to the options.coercionType parameter.

setSelectedDataAsync(data: string, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameters

data

string

The string that will replace the existing body. The string is limited to 1,000,000 characters.

callback

(asyncResult: Office.AsyncResult<void>) => void

Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type Office.AsyncResult. Any errors encountered will be provided in the asyncResult.error property.

Returns

void

Remarks

[ API set: Mailbox 1.1 ]

Minimum permission level: read/write item

Applicable Outlook mode: Compose

Errors:

• DataExceedsMaximumSize: The data parameter is longer than 1,000,000 characters.

• InvalidFormatError: The options.coercionType parameter is set to Office.CoercionType.Html and the message body is in plain text.