Edit

Share via

Office.Body interface

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

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/20-item-body/add-inline-base64-image.yaml

const mailItem = Office.context.mailbox.item;
const base64String =
  "iVBORw0KGgoAAAANSUhEUgAAAGAAAABgCAMAAADVRocKAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAnUExURQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAN0S+bUAAAAMdFJOUwAQIDBAUI+fr7/P7yEupu8AAAAJcEhZcwAADsMAAA7DAcdvqGQAAAF8SURBVGhD7dfLdoMwDEVR6Cspzf9/b20QYOthS5Zn0Z2kVdY6O2WULrFYLBaLxd5ur4mDZD14b8ogWS/dtxV+dmx9ysA2QUj9TQRWv5D7HyKwuIW9n0vc8tkpHP0W4BOg3wQ8wtlvA+PC1e8Ao8Ld7wFjQtHvAiNC2e8DdqHqKwCrUPc1gE1AfRVgEXBfB+gF0lcCWoH2tYBOYPpqQCNwfT3QF9i+AegJfN8CtAWhbwJagtS3AbIg9o2AJMh9M5C+SVGBvx6zAfmT0r+Bv8JMwP4kyFPir+cswF5KL3WLv14zAFBCLf56Tw9cparFX4upgaJUtPhrOS1QlY5W+vWTXrGgBFB/b72ev3/0igUdQPppP/nfowfKUUEFcP207y/yxKmgAYQ+PywoAFOfCH3A2MdCFzD3kdADBvq10AGG+pXQBgb7pdAEhvuF0AIc/VtoAK7+JciAs38KIuDugyAC/v4hiMCE/i7IwLRBsh68N2WQjMVisVgs9i5bln8LGScNcCrONQAAAABJRU5ErkJggg==";

// Get the current body of the message or appointment.
mailItem.body.getAsync(Office.CoercionType.Html, (bodyResult) => {
  if (bodyResult.status === Office.AsyncResultStatus.Succeeded) {
    // Insert the Base64-encoded image to the beginning of the body.
    const options = { isInline: true, asyncContext: bodyResult.value };
    mailItem.addFileAttachmentFromBase64Async(base64String, "sample.png", options, (attachResult) => {
      if (attachResult.status === Office.AsyncResultStatus.Succeeded) {
        let body = attachResult.asyncContext;
        body = body.replace("<p class=MsoNormal>", `<p class=MsoNormal><img src="cid:sample.png">`);

        mailItem.body.setAsync(body, { coercionType: Office.CoercionType.Html }, (setResult) => {
          if (setResult.status === Office.AsyncResultStatus.Succeeded) {
            console.log("Inline Base64-encoded image added to the body.");
          } else {
            console.log(setResult.error.message);
          }
        });
      } else {
        console.log(attachResult.error.message);
      }
    });
  } else {
    console.log(bodyResult.error.message);
  }
});

Methods

getAsync(coercionType, options, callback)

Returns the current body in a specified format.

This method returns the entire current body in the format specified by coercionType.
getAsync(coercionType, callback)

Returns the current body in a specified format.

This method returns the entire current body in the format specified by coercionType.
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.
setAsync(data, options, callback)

Replaces the entire body with the specified text.
setAsync(data, callback)

Replaces the entire body with the specified text.
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.
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.

Method Details

getAsync(coercionType, options, callback)

Returns the current body in a specified format.

This method returns the entire current body in the format specified by coercionType.

getAsync(coercionType: Office.CoercionType | string, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<string>) => void): void;

Parameters

coercionType

Office.CoercionType | string

The format for the returned body.

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<string>) => void

Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type Office.AsyncResult. The body is provided in the requested format in the asyncResult.value property.

Returns

void

Remarks

[ API set: Mailbox 1.3 ]

Minimum permission level: read item

Applicable Outlook mode: Compose or Read

Important:

  • When working with HTML-formatted bodies, it's important to note that the value returned by the Body.getAsync method won't necessarily be the exact same value that was previously passed in the Body.setAsync method. The client may modify the value passed to setAsync to make it render efficiently with its rendering engine.

  • In Outlook on the web and new Outlook on Windows, if the body contains formatted elements, such as tables, lists, and links, specify Office.CoercionType.Html in the getAsync call. Otherwise, you may receive an unexpected value, such as an empty string.

Examples

// This example gets the body of the item as plain text.
Office.context.mailbox.item.body.getAsync(
    "text",
    { asyncContext: "This is passed to the callback" },
    function callback(result) {
        // Do something with the result.
    });

// The following is an example of the result parameter passed to the callback function.
{
    "value": "TEXT of whole body (including threads below)",
    "status": "succeeded",
    "asyncContext": "This is passed to the callback"
}

getAsync(coercionType, callback)

Returns the current body in a specified format.

This method returns the entire current body in the format specified by coercionType.

getAsync(coercionType: Office.CoercionType | string, callback?: (asyncResult: Office.AsyncResult<string>) => void): void;

Parameters

coercionType

Office.CoercionType | string

The format for the returned body.

callback

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

Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type Office.AsyncResult. The body is provided in the requested format in the asyncResult.value property.

Returns

void

Remarks

[ API set: Mailbox 1.3 ]

Minimum permission level: read item

Applicable Outlook mode: Compose or Read

Important:

  • When working with HTML-formatted bodies, it's important to note that the value returned by the Body.getAsync method won't necessarily be the exact same value that was previously passed in the Body.setAsync method. The client may modify the value passed to setAsync to make it render efficiently with its rendering engine.

  • In Outlook on the web and new Outlook on Windows, if the body contains formatted elements, such as tables, lists, and links, specify Office.CoercionType.Html in the getAsync call. Otherwise, you may receive an unexpected value, such as an empty string.

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/20-item-body/add-inline-base64-image.yaml

const mailItem = Office.context.mailbox.item;
const base64String =
  "iVBORw0KGgoAAAANSUhEUgAAAGAAAABgCAMAAADVRocKAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAnUExURQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAN0S+bUAAAAMdFJOUwAQIDBAUI+fr7/P7yEupu8AAAAJcEhZcwAADsMAAA7DAcdvqGQAAAF8SURBVGhD7dfLdoMwDEVR6Cspzf9/b20QYOthS5Zn0Z2kVdY6O2WULrFYLBaLxd5ur4mDZD14b8ogWS/dtxV+dmx9ysA2QUj9TQRWv5D7HyKwuIW9n0vc8tkpHP0W4BOg3wQ8wtlvA+PC1e8Ao8Ld7wFjQtHvAiNC2e8DdqHqKwCrUPc1gE1AfRVgEXBfB+gF0lcCWoH2tYBOYPpqQCNwfT3QF9i+AegJfN8CtAWhbwJagtS3AbIg9o2AJMh9M5C+SVGBvx6zAfmT0r+Bv8JMwP4kyFPir+cswF5KL3WLv14zAFBCLf56Tw9cparFX4upgaJUtPhrOS1QlY5W+vWTXrGgBFB/b72ev3/0igUdQPppP/nfowfKUUEFcP207y/yxKmgAYQ+PywoAFOfCH3A2MdCFzD3kdADBvq10AGG+pXQBgb7pdAEhvuF0AIc/VtoAK7+JciAs38KIuDugyAC/v4hiMCE/i7IwLRBsh68N2WQjMVisVgs9i5bln8LGScNcCrONQAAAABJRU5ErkJggg==";

// Get the current body of the message or appointment.
mailItem.body.getAsync(Office.CoercionType.Html, (bodyResult) => {
  if (bodyResult.status === Office.AsyncResultStatus.Succeeded) {
    // Insert the Base64-encoded image to the beginning of the body.
    const options = { isInline: true, asyncContext: bodyResult.value };
    mailItem.addFileAttachmentFromBase64Async(base64String, "sample.png", options, (attachResult) => {
      if (attachResult.status === Office.AsyncResultStatus.Succeeded) {
        let body = attachResult.asyncContext;
        body = body.replace("<p class=MsoNormal>", `<p class=MsoNormal><img src="cid:sample.png">`);

        mailItem.body.setAsync(body, { coercionType: Office.CoercionType.Html }, (setResult) => {
          if (setResult.status === Office.AsyncResultStatus.Succeeded) {
            console.log("Inline Base64-encoded image added to the body.");
          } else {
            console.log(setResult.error.message);
          }
        });
      } else {
        console.log(attachResult.error.message);
      }
    });
  } else {
    console.log(bodyResult.error.message);
  }
});

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

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

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 (new and classic), the cursor position remains the same in the preexisting 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 preexisting 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.

  • SVG files aren't supported. Use JPG or PNG files instead.

  • The prependAsync method doesn't support inline CSS. Use internal or external CSS instead.

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="https://www.contoso.com">Click here!</a>'.
*/
const text = $("#text-field").val().toString();

// 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

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

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 (new and classic), the cursor position remains the same in the preexisting 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 preexisting 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.

  • SVG files aren't supported. Use JPG or PNG files instead.

  • The prependAsync method doesn't support inline CSS. Use internal or external CSS instead.

Errors:

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

setAsync(data, options, callback)

Replaces the entire body with the specified text.

setAsync(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.3 ]

Minimum permission level: read/write item

Applicable Outlook mode: Compose

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

Important:

  • After the body is replaced with the specified content, the position of the cursor depends on which client the add-in is running. In classic Outlook on Windows, the cursor appears at the beginning of the body of the mail item. In Outlook on the web and new Outlook on Windows, the cursor appears at the end of the body of the mail item. 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 value returned by the Body.getAsync method won't necessarily be the exact same value that was previously passed in the Body.setAsync method. The client may modify the value passed to setAsync to make it render efficiently with its rendering engine.

  • 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 Windows and on Mac, the add-in user isn't able to revert this action with the Undo command.

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

  • SVG files aren't supported. Use JPG or PNG files instead.

  • The setAsync method doesn't support inline CSS. Use internal or external CSS instead.

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

// When including links in HTML markup, you can disable online link preview
// by setting the id attribute on the anchor (<a>) to "LPNoLP".
Office.context.mailbox.item.body.setAsync(
    '<a id="LPNoLP" href="http://www.contoso.com">Click here!</a>',
    { 
        coercionType: Office.CoercionType.Html,
        asyncContext: "This is passed to the callback"
    },
    (result) => {
        // Process the result.
    }
);

// The following is an example of the result parameter passed to the callback function.
{
    "value": null,
    "status": "succeeded",
    "asyncContext": "This is passed to the callback"
}

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/20-item-body/add-inline-base64-image.yaml

const mailItem = Office.context.mailbox.item;
const base64String =
  "iVBORw0KGgoAAAANSUhEUgAAAGAAAABgCAMAAADVRocKAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAnUExURQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAN0S+bUAAAAMdFJOUwAQIDBAUI+fr7/P7yEupu8AAAAJcEhZcwAADsMAAA7DAcdvqGQAAAF8SURBVGhD7dfLdoMwDEVR6Cspzf9/b20QYOthS5Zn0Z2kVdY6O2WULrFYLBaLxd5ur4mDZD14b8ogWS/dtxV+dmx9ysA2QUj9TQRWv5D7HyKwuIW9n0vc8tkpHP0W4BOg3wQ8wtlvA+PC1e8Ao8Ld7wFjQtHvAiNC2e8DdqHqKwCrUPc1gE1AfRVgEXBfB+gF0lcCWoH2tYBOYPpqQCNwfT3QF9i+AegJfN8CtAWhbwJagtS3AbIg9o2AJMh9M5C+SVGBvx6zAfmT0r+Bv8JMwP4kyFPir+cswF5KL3WLv14zAFBCLf56Tw9cparFX4upgaJUtPhrOS1QlY5W+vWTXrGgBFB/b72ev3/0igUdQPppP/nfowfKUUEFcP207y/yxKmgAYQ+PywoAFOfCH3A2MdCFzD3kdADBvq10AGG+pXQBgb7pdAEhvuF0AIc/VtoAK7+JciAs38KIuDugyAC/v4hiMCE/i7IwLRBsh68N2WQjMVisVgs9i5bln8LGScNcCrONQAAAABJRU5ErkJggg==";

// Get the current body of the message or appointment.
mailItem.body.getAsync(Office.CoercionType.Html, (bodyResult) => {
  if (bodyResult.status === Office.AsyncResultStatus.Succeeded) {
    // Insert the Base64-encoded image to the beginning of the body.
    const options = { isInline: true, asyncContext: bodyResult.value };
    mailItem.addFileAttachmentFromBase64Async(base64String, "sample.png", options, (attachResult) => {
      if (attachResult.status === Office.AsyncResultStatus.Succeeded) {
        let body = attachResult.asyncContext;
        body = body.replace("<p class=MsoNormal>", `<p class=MsoNormal><img src="cid:sample.png">`);

        mailItem.body.setAsync(body, { coercionType: Office.CoercionType.Html }, (setResult) => {
          if (setResult.status === Office.AsyncResultStatus.Succeeded) {
            console.log("Inline Base64-encoded image added to the body.");
          } else {
            console.log(setResult.error.message);
          }
        });
      } else {
        console.log(attachResult.error.message);
      }
    });
  } else {
    console.log(bodyResult.error.message);
  }
});

setAsync(data, callback)

Replaces the entire body with the specified text.

setAsync(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.3 ]

Minimum permission level: read/write item

Applicable Outlook mode: Compose

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

Important:

  • After the body is replaced with the specified content, the position of the cursor depends on which client the add-in is running. In classic Outlook on Windows, the cursor appears at the beginning of the body of the mail item. In Outlook on the web and new Outlook on Windows, the cursor appears at the end of the body of the mail item. 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 value returned by the Body.getAsync method won't necessarily be the exact same value that was previously passed in the Body.setAsync method. The client may modify the value passed to setAsync to make it render efficiently with its rendering engine.

  • 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 Windows and on Mac, the add-in user isn't able to revert this action with the Undo command.

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

  • SVG files aren't supported. Use JPG or PNG files instead.

  • The setAsync method doesn't support inline CSS. Use internal or external CSS instead.

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.

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.

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

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

*Important:

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

  • SVG files aren't supported. Use JPG or PNG files instead.

  • The setSelectedDataAsync method doesn't support inline CSS. Use internal or external CSS instead.

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="https://www.contoso.com">Click here!</a>'.
*/
const text = $("#text-field").val().toString();

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

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

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

*Important:

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

  • SVG files aren't supported. Use JPG or PNG files instead.

  • The setSelectedDataAsync method doesn't support inline CSS. Use internal or external CSS instead.

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.