Office.Body interface

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: ReadItem

Applicable Outlook mode: Compose or Read

Methods

appendOnSendAsync(data, options, callback)

Appends on send the specified content to the end of the item 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: If your add-in implements the on-send feature and calls appendOnSendAsync in the ItemSend handler, the appendOnSendAsync call returns an error as this scenario is not supported.

Important: To use appendOnSendAsync, the ExtendedPermissions manifest node must include the AppendOnSend extended permission.

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

appendOnSendAsync(data, callback)

Appends on send the specified content to the end of the item 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: If your add-in implements the on-send feature and calls appendOnSendAsync in the ItemSend handler, the appendOnSendAsync call returns an error as this scenario is not supported.

Important: To use appendOnSendAsync, the ExtendedPermissions manifest node must include the AppendOnSend extended permission.

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

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.

When working with HTML-formatted bodies, it is important to note that the Body.getAsync and Body.setAsync methods are not idempotent. The value returned from the getAsync method will not necessarily be exactly the same as the value that was passed in the setAsync method previously. The client may modify the value passed to setAsync in order to make it render efficiently with its rendering engine.

getAsync(coercionType, callback)

Returns the current body in a specified format.

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

When working with HTML-formatted bodies, it is important to note that the Body.getAsync and Body.setAsync methods are not idempotent. The value returned from the getAsync method will not necessarily be exactly the same as the value that was passed in the setAsync method previously. The client may modify the value passed to setAsync in order to make it render efficiently with its rendering engine.

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.

The prependAsync method inserts the specified string at the beginning of the item body. After insertion, the cursor is returned to its original place, relative to the inserted content.

When working with HTML-formatted bodies, it's important to note that the client may modify the value passed to prependAsync in order to make it render efficiently with its rendering engine. This means that the value returned from a subsequent call to Body.getAsync method will not necessarily exactly contain the value that was passed in the prependAsync method previously.

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

prependAsync(data, callback)

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

The prependAsync method inserts the specified string at the beginning of the item body. After insertion, the cursor is returned to its original place, relative to the inserted content.

When working with HTML-formatted bodies, it's important to note that the client may modify the value passed to prependAsync in order to make it render efficiently with its rendering engine. This means that the value returned from a subsequent call to Body.getAsync method will not necessarily exactly contain the value that was passed in the prependAsync method previously.

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

setAsync(data, options, callback)

Replaces the entire body with the specified text.

When working with HTML-formatted bodies, it is important to note that the Body.getAsync and Body.setAsync methods are not idempotent. The value returned from the getAsync method will not necessarily be exactly the same as the value that was passed in the setAsync method previously. The client may modify the value passed to setAsync in order 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).

setAsync(data, callback)

Replaces the entire body with the specified text.

When working with HTML-formatted bodies, it is important to note that the Body.getAsync and Body.setAsync methods are not idempotent. The value returned from the getAsync method will not necessarily be exactly the same as the value that was passed in the setAsync method previously. The client may modify the value passed to setAsync in order 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).

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

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

Method Details

appendOnSendAsync(data, options, callback)

Appends on send the specified content to the end of the item 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: If your add-in implements the on-send feature and calls appendOnSendAsync in the ItemSend handler, the appendOnSendAsync call returns an error as this scenario is not supported.

Important: To use appendOnSendAsync, the ExtendedPermissions manifest node must include the AppendOnSend extended permission.

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

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

Parameters

data

string

The string to be added to the end of the body. The string is limited to 5,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 method. coercionType: The desired format for the data to be appended. 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.9 ]

Minimum permission level: ReadWriteItem

Applicable Outlook mode: Compose

Errors:

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

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

Examples

Office.context.mailbox.item.body.appendOnSendAsync(
    "P.S. This text was appended on send.",
    {coercionType: Office.CoercionType.Html},
    function (asyncResult) {
        if (asyncResult.status === Office.AsyncResultStatus.Failed) {
            console.log("Action failed with error: " + asyncResult.error.message);
        }
    }
);

appendOnSendAsync(data, callback)

Appends on send the specified content to the end of the item 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: If your add-in implements the on-send feature and calls appendOnSendAsync in the ItemSend handler, the appendOnSendAsync call returns an error as this scenario is not supported.

Important: To use appendOnSendAsync, the ExtendedPermissions manifest node must include the AppendOnSend extended permission.

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

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

Parameters

data

string

The string to be added to the end of the body. The string is limited to 5,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.9 ]

Minimum permission level: ReadWriteItem

Applicable Outlook mode: Compose

Errors:

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

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

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.

When working with HTML-formatted bodies, it is important to note that the Body.getAsync and Body.setAsync methods are not idempotent. The value returned from the getAsync method will not necessarily be exactly the same as the value that was passed in the setAsync method previously. The client may modify the value passed to setAsync in order to make it render efficiently with its rendering engine.

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

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: ReadItem

Applicable Outlook mode: Compose or Read

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.

When working with HTML-formatted bodies, it is important to note that the Body.getAsync and Body.setAsync methods are not idempotent. The value returned from the getAsync method will not necessarily be exactly the same as the value that was passed in the setAsync method previously. The client may modify the value passed to setAsync in order to make it render efficiently with its rendering engine.

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: ReadItem

Applicable Outlook mode: Compose or Read

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

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: ReadItem

Applicable Outlook mode: Compose

Examples

Office.context.mailbox.item.body.getTypeAsync(function (asyncResult) {
    if (asyncResult.status === "failed") {
        console.log("Action failed with error: " + asyncResult.error.message);
    } else {
        console.log("Body type: " + 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: ReadItem

Applicable Outlook mode: Compose

prependAsync(data, options, callback)

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

The prependAsync method inserts the specified string at the beginning of the item body. After insertion, the cursor is returned to its original place, relative to the inserted content.

When working with HTML-formatted bodies, it's important to note that the client may modify the value passed to prependAsync in order to make it render efficiently with its rendering engine. This means that the value returned from a subsequent call to Body.getAsync method will not necessarily exactly contain the value that was passed in the prependAsync method previously.

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

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 method. 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: ReadWriteItem

Applicable Outlook mode: Compose

Errors:

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

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.prependAsync(
    '<a id="LPNoLP" href="http://www.contoso.com">Click here!</a>',
    {coercionType: Office.CoercionType.Html},
    callback);

prependAsync(data, callback)

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

The prependAsync method inserts the specified string at the beginning of the item body. After insertion, the cursor is returned to its original place, relative to the inserted content.

When working with HTML-formatted bodies, it's important to note that the client may modify the value passed to prependAsync in order to make it render efficiently with its rendering engine. This means that the value returned from a subsequent call to Body.getAsync method will not necessarily exactly contain the value that was passed in the prependAsync method previously.

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

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: ReadWriteItem

Applicable Outlook mode: Compose

Errors:

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

setAsync(data, options, callback)

Replaces the entire body with the specified text.

When working with HTML-formatted bodies, it is important to note that the Body.getAsync and Body.setAsync methods are not idempotent. The value returned from the getAsync method will not necessarily be exactly the same as the value that was passed in the setAsync method previously. The client may modify the value passed to setAsync in order 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).

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 method. 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: ReadWriteItem

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

// 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},
    callback);
Office.context.mailbox.item.body.setAsync(
    "<b>(replaces all body, including threads you are replying to that may be on the bottom)</b>",
    { coercionType: "html", asyncContext: "This is passed to the callback" },
    function 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"
}

setAsync(data, callback)

Replaces the entire body with the specified text.

When working with HTML-formatted bodies, it is important to note that the Body.getAsync and Body.setAsync methods are not idempotent. The value returned from the getAsync method will not necessarily be exactly the same as the value that was passed in the setAsync method previously. The client may modify the value passed to setAsync in order 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).

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: ReadWriteItem

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.

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

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 method. 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: ReadWriteItem

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

// 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.setSelectedDataAsync(
    '<a id="LPNoLP" href="http://www.contoso.com">Click here!</a>',
    {coercionType: Office.CoercionType.Html},
    callback);

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

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: ReadWriteItem

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.