Office.MessageCompose interface

Reference

Package:: outlook

The message compose mode of Office.context.mailbox.item.

Important:

This is an internal Outlook object, not directly exposed through existing interfaces. You should treat this as a mode of Office.context.mailbox.item. For more information, refer to the Object Model page.
When calling Office.context.mailbox.item on a message, note that the Reading Pane in the Outlook client must be turned on. For guidance on how to configure the Reading Pane, see Use and configure the Reading Pane to preview messages.

Parent interfaces:

Extends: Office.Message

Properties

bcc	Gets an object that provides methods to get or update the recipients on the Bcc (blind carbon copy) line of a message. Depending on the client/platform (i.e., Windows, Mac, etc.), limits may apply on how many recipients you can get or update. See the Recipients object for more details.
body	Gets an object that provides methods for manipulating the body of an item.
cc	Provides access to the Cc (carbon copy) recipients of a message. The type of object and level of access depend on the mode of the current item. The `cc` property returns a `Recipients` object that provides methods to get or update the recipients on the Cc line of the message. However, depending on the client/platform (i.e., Windows, Mac, etc.), limits may apply on how many recipients you can get or update. See the Recipients object for more details.
conversationId	Gets an identifier for the email conversation that contains a particular message. You can get an integer for this property if your mail app is activated in read forms or responses in compose forms. If subsequently the user changes the subject of the reply message, upon sending the reply, the conversation ID for that message will change and that value you obtained earlier will no longer apply. You get null for this property for a new item in a compose form. If the user sets a subject and saves the item, the `conversationId` property will return a value.
itemType	Gets the type of item that an instance represents. The `itemType` property returns one of the `ItemType` enumeration values, indicating whether the item object instance is a message or an appointment.
subject	Gets or sets the description that appears in the subject field of an item. The `subject` property gets or sets the entire subject of the item, as sent by the email server. The `subject` property returns a `Subject` object that provides methods to get and set the subject.
to	Provides access to the recipients on the To line of a message. The type of object and level of access depend on the mode of the current item. The `to` property returns a `Recipients` object that provides methods to get or update the recipients on the To line of the message. However, depending on the client/platform (i.e., Windows, Mac, etc.), limits may apply on how many recipients you can get or update. See the Recipients object for more details.

Methods

addFileAttachmentAsync(uri, attachmentName, options, callback)	Adds a file to a message or appointment as an attachment. The `addFileAttachmentAsync` method uploads the file at the specified URI and attaches it to the item in the compose form.
addFileAttachmentAsync(uri, attachmentName, callback)	Adds a file to a message or appointment as an attachment. The `addFileAttachmentAsync` method uploads the file at the specified URI and attaches it to the item in the compose form.
addItemAttachmentAsync(itemId, attachmentName, options, callback)	Adds an Exchange item, such as a message, as an attachment to the message or appointment. The `addItemAttachmentAsync` method attaches the item with the specified Exchange identifier to the item in the compose form. If you specify a callback function, the method is called with one parameter, `asyncResult`, which contains either the attachment identifier or a code that indicates any error that occurred while attaching the item. You can use the options parameter to pass state information to the callback function, if needed. You can subsequently use the identifier with the `removeAttachmentAsync` method to remove the attachment in the same session. If your Office Add-in is running in Outlook on the web or new Outlook on Windows, the `addItemAttachmentAsync` method can attach items to items other than the item that you are editing. However, this isn't supported and isn't recommended.
addItemAttachmentAsync(itemId, attachmentName, callback)	Adds an Exchange item, such as a message, as an attachment to the message or appointment. The `addItemAttachmentAsync` method attaches the item with the specified Exchange identifier to the item in the compose form. If you specify a callback function, the method is called with one parameter, `asyncResult`, which contains either the attachment identifier or a code that indicates any error that occurred while attaching the item. You can use the options parameter to pass state information to the callback function, if needed. You can subsequently use the identifier with the `removeAttachmentAsync` method to remove the attachment in the same session. If your Office Add-in is running in Outlook on the web or new Outlook on Windows, the `addItemAttachmentAsync` method can attach items to items other than the item that you are editing. However, this isn't supported and isn't recommended.
getSelectedDataAsync(coercionType, options, callback)	Asynchronously returns selected data from the subject or body of a message. If there is no selection but the cursor is in the body or subject, the method returns an empty string for the selected data. If a field other than the body or subject is selected, the method returns the `InvalidSelection` error. To access the selected data from the callback function, call `asyncResult.value.data`. To access the source property that the selection comes from, call `asyncResult.value.sourceProperty`, which will be either `body` or `subject`.
getSelectedDataAsync(coercionType, callback)	Asynchronously returns selected data from the subject or body of a message. If there is no selection but the cursor is in the body or subject, the method returns an empty string for the selected data. If a field other than the body or subject is selected, the method returns the `InvalidSelection` error. To access the selected data from the callback function, call `asyncResult.value.data`. To access the source property that the selection comes from, call `asyncResult.value.sourceProperty`, which will be either `body` or `subject`.
loadCustomPropertiesAsync(callback, userContext)	Asynchronously loads custom properties for this add-in on the selected item. Custom properties are stored as key-value pairs on a per-app, per-item basis. This method returns a CustomProperties object in the callback, which provides methods to access the custom properties specific to the current item and the current add-in. Custom properties aren't encrypted on the item, so this shouldn't be used as secure storage. The custom properties are provided as a `CustomProperties` object in the `asyncResult.value` property. This object can be used to get, set, save, and remove custom properties from the mail item.
removeAttachmentAsync(attachmentId, options, callback)	Removes an attachment from a message or appointment. The `removeAttachmentAsync` method removes the attachment with the specified identifier from the item. As a best practice, you should use the attachment identifier to remove an attachment only if the same mail app has added that attachment in the same session. In Outlook on the web, on mobile devices, and in new Outlook on Windows, the attachment identifier is valid only within the same session. A session is over when the user closes the app, or if the user starts composing an inline form then subsequently pops out the form to continue in a separate window.
removeAttachmentAsync(attachmentId, callback)	Removes an attachment from a message or appointment. The `removeAttachmentAsync` method removes the attachment with the specified identifier from the item. As a best practice, you should use the attachment identifier to remove an attachment only if the same mail app has added that attachment in the same session. In Outlook on the web, on mobile devices, and in new Outlook on Windows, the attachment identifier is valid only within the same session. A session is over when the user closes the app, or if the user starts composing an inline form then subsequently pops out the form to continue in a separate window.
setSelectedDataAsync(data, options, callback)	Asynchronously inserts data into the body or subject of a message. The `setSelectedDataAsync` method inserts the specified string at the cursor location in the subject or body of the item, or, if text is selected in the editor, it replaces the selected text. If the cursor is not in the body or subject field, an error is returned. After insertion, the cursor is placed at the end of the inserted content.
setSelectedDataAsync(data, callback)	Asynchronously inserts data into the body or subject of a message. The `setSelectedDataAsync` method inserts the specified string at the cursor location in the subject or body of the item, or, if text is selected in the editor, it replaces the selected text. If the cursor is not in the body or subject field, an error is returned. After insertion, the cursor is placed at the end of the inserted content.

Property Details

bcc

Gets an object that provides methods to get or update the recipients on the Bcc (blind carbon copy) line of a message.

Depending on the client/platform (i.e., Windows, Mac, etc.), limits may apply on how many recipients you can get or update. See the Recipients object for more details.

bcc: Recipients;

Property Value

Office.Recipients

Remarks

[ API set: Mailbox 1.1 ]

Minimum permission level: read item

Applicable Outlook mode: Message Compose

Examples

Office.context.mailbox.item.bcc.setAsync( ['alice@contoso.com', 'bob@contoso.com'] );
Office.context.mailbox.item.bcc.addAsync( ['jason@contoso.com'] );
Office.context.mailbox.item.bcc.getAsync(callback);

function callback(asyncResult) {
    const arrayOfBccRecipients = asyncResult.value;
}

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/30-recipients-and-attendees/get-set-bcc-message-compose.yaml

Office.context.mailbox.item.bcc.getAsync(function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    const msgBcc = asyncResult.value;
    console.log("Message being blind-copied to:");
    for (let i = 0; i < msgBcc.length; i++) {
      console.log(msgBcc[i].displayName + " (" + msgBcc[i].emailAddress + ")");
    }
  } else {
    console.error(asyncResult.error);
  }
});

...

const email = $("#emailBcc")
  .val()
  .toString();
const emailArray = [email];
Office.context.mailbox.item.bcc.setAsync(emailArray, function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    console.log("Succeeded in setting Bcc field.");
  } else {
    console.error(asyncResult.error);
  }
});

body

Gets an object that provides methods for manipulating the body of an item.

body: Body;

Property Value

Office.Body

Remarks

[ API set: Mailbox 1.1 ]

Minimum permission level: read item

Applicable Outlook mode: Message Compose

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"
}

cc

Provides access to the Cc (carbon copy) recipients of a message. The type of object and level of access depend on the mode of the current item.

The cc property returns a Recipients object that provides methods to get or update the recipients on the Cc line of the message. However, depending on the client/platform (i.e., Windows, Mac, etc.), limits may apply on how many recipients you can get or update. See the Recipients object for more details.

cc: Recipients;

Property Value

Office.Recipients

Remarks

Minimum permission level: read item

Applicable Outlook mode: Message Compose

Examples

Office.context.mailbox.item.cc.setAsync( ['alice@contoso.com', 'bob@contoso.com'] );
Office.context.mailbox.item.cc.addAsync( ['jason@contoso.com'] );
Office.context.mailbox.item.cc.getAsync(callback);

function callback(asyncResult) {
    const arrayOfCcRecipients = asyncResult.value;
}

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/30-recipients-and-attendees/get-set-cc-message-compose.yaml

Office.context.mailbox.item.cc.getAsync(function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    const msgCc = asyncResult.value;
    console.log("Message being copied to:");
    for (let i = 0; i < msgCc.length; i++) {
      console.log(msgCc[i].displayName + " (" + msgCc[i].emailAddress + ")");
    }
  } else {
    console.error(asyncResult.error);
  }
});

...

const email = $("#emailCc")
  .val()
  .toString();
const emailArray = [email];
Office.context.mailbox.item.cc.setAsync(emailArray, function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    console.log("Succeeded in setting Cc field.");
  } else {
    console.error(asyncResult.error);
  }
});

conversationId

Gets an identifier for the email conversation that contains a particular message.

You can get an integer for this property if your mail app is activated in read forms or responses in compose forms. If subsequently the user changes the subject of the reply message, upon sending the reply, the conversation ID for that message will change and that value you obtained earlier will no longer apply.

You get null for this property for a new item in a compose form. If the user sets a subject and saves the item, the conversationId property will return a value.

conversationId: string;

Property Value

string

Remarks

Minimum permission level: read item

Applicable Outlook mode: Message Compose

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/90-other-item-apis/get-conversation-id-message.yaml

console.log(`Conversation ID: ${Office.context.mailbox.item.conversationId}`);

itemType

Gets the type of item that an instance represents.

The itemType property returns one of the ItemType enumeration values, indicating whether the item object instance is a message or an appointment.

itemType: MailboxEnums.ItemType | string;

Property Value

Office.MailboxEnums.ItemType | string

Remarks

Minimum permission level: read item

Applicable Outlook mode: Message Compose

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/90-other-item-apis/get-item-type.yaml

const itemType = Office.context.mailbox.item.itemType;
switch (itemType) {
    case Office.MailboxEnums.ItemType.Appointment:
        console.log(`Current item is an ${itemType}.`);
        break;
    case Office.MailboxEnums.ItemType.Message:
        console.log(`Current item is a ${itemType}. A message could be an email, meeting request, meeting response, or meeting cancellation.`);
        break;
}

subject

Gets or sets the description that appears in the subject field of an item.

The subject property gets or sets the entire subject of the item, as sent by the email server.

The subject property returns a Subject object that provides methods to get and set the subject.

subject: Subject;

Property Value

Office.Subject

Remarks

Minimum permission level: read item

Applicable Outlook mode: Message Compose

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/90-other-item-apis/get-set-subject-compose.yaml

Office.context.mailbox.item.subject.getAsync((result) => {
  if (result.status !== Office.AsyncResultStatus.Succeeded) {
    console.error(`Action failed with message ${result.error.message}`);
    return;
  }
  console.log(`Subject: ${result.value}`);
});

...

let subject = "Hello World!";
Office.context.mailbox.item.subject.setAsync(subject, (result) => {
  if (result.status !== Office.AsyncResultStatus.Succeeded) {
    console.error(`Action failed with message ${result.error.message}`);
    return;
  }
  console.log(`Successfully set subject to ${subject}`);
});

to

Provides access to the recipients on the To line of a message. The type of object and level of access depend on the mode of the current item.

The to property returns a Recipients object that provides methods to get or update the recipients on the To line of the message. However, depending on the client/platform (i.e., Windows, Mac, etc.), limits may apply on how many recipients you can get or update. See the Recipients object for more details.

to: Recipients;

Property Value

Office.Recipients

Remarks

Minimum permission level: read item

Applicable Outlook mode: Message Compose

Examples

Office.context.mailbox.item.to.setAsync( ['alice@contoso.com', 'bob@contoso.com'] );
Office.context.mailbox.item.to.addAsync( ['jason@contoso.com'] );
Office.context.mailbox.item.to.getAsync(callback);

function callback(asyncResult) {
    const arrayOfToRecipients = asyncResult.value;
}

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/30-recipients-and-attendees/get-set-to-message-compose.yaml

Office.context.mailbox.item.to.getAsync(function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    const msgTo = asyncResult.value;
    console.log("Message being sent to:");
    for (let i = 0; i < msgTo.length; i++) {
      console.log(msgTo[i].displayName + " (" + msgTo[i].emailAddress + ")");
    }
  } else {
    console.error(asyncResult.error);
  }
});

...

const email = $("#emailTo")
  .val()
  .toString();
const emailArray = [email];
Office.context.mailbox.item.to.setAsync(emailArray, function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    console.log("Succeeded in setting To field.");
  } else {
    console.error(asyncResult.error);
  }
});

Method Details

addFileAttachmentAsync(uri, attachmentName, options, callback)

Adds a file to a message or appointment as an attachment.

The addFileAttachmentAsync method uploads the file at the specified URI and attaches it to the item in the compose form.

addFileAttachmentAsync(uri: string, attachmentName: string, options: Office.AsyncContextOptions & { isInline: boolean }, callback?: (asyncResult: Office.AsyncResult<string>) => void): void;

Parameters

uri: string

The URI that provides the location of the file to attach to the message or appointment. The maximum length is 2048 characters.

attachmentName: string

The name of the attachment that is shown while the attachment is uploading. The maximum length is 255 characters.

options: Office.AsyncContextOptions & { isInline: boolean }

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. isInline: If true, indicates that the attachment will be shown inline as an image in the message body and won't be displayed in the attachment list.

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. On success, the attachment identifier will be provided in the asyncResult.value property. If uploading the attachment fails, the asyncResult object will contain an Error object that provides a description of the error.

Returns

void

Remarks

[ API set: Mailbox 1.1 for Outlook on Windows (classic) and on Mac, Mailbox 1.8 for Outlook on the web and new Outlook on Windows ]

Minimum permission level: read/write item

Applicable Outlook mode: Message Compose

Important:

This method isn't supported in Outlook on iOS or Android. For more information on supported APIs in Outlook mobile, see Outlook JavaScript APIs supported in Outlook on mobile devices.
In recent builds of classic Outlook on Windows, a bug was introduced that incorrectly appends an Authorization: Bearer header to this action (whether using this API or the Outlook UI). To work around this issue, use the addFileAttachmentFromBase64 API introduced with requirement set 1.8.
The URI of the file to be attached must support caching in production. The server hosting the image shouldn't return a Cache-Control header that specifies no-cache, no-store, or similar options in the HTTP response. However, when you're developing the add-in and making changes to files, caching can prevent you from seeing your changes. We recommend using Cache-Control headers during development.
You can use the same URI with the removeAttachmentAsync method to remove the attachment in the same session.

Errors:

AttachmentSizeExceeded: The attachment is larger than allowed.
FileTypeNotSupported: The attachment has an extension that is not allowed.
NumberOfAttachmentsExceeded: The message or appointment has too many attachments.

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/40-attachments/attachments-compose.yaml

const attachmentUrl = $("#attachmentUrl")
  .val()
  .toString();
Office.context.mailbox.item.addFileAttachmentAsync(
  attachmentUrl,
  getFileName(attachmentUrl),
  { isInline: false },
  (result) => {
    console.log(result);
  }
);

addFileAttachmentAsync(uri, attachmentName, callback)

Adds a file to a message or appointment as an attachment.

The addFileAttachmentAsync method uploads the file at the specified URI and attaches it to the item in the compose form.

addFileAttachmentAsync(uri: string, attachmentName: string, callback?: (asyncResult: Office.AsyncResult<string>) => void): void;

Parameters

uri: string

The URI that provides the location of the file to attach to the message or appointment. The maximum length is 2048 characters.

attachmentName: string

The name of the attachment that is shown while the attachment is uploading. The maximum length is 255 characters.

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

Returns

void

Remarks

[ API set: Mailbox 1.1 for Outlook on Windows (classic) and on Mac, Mailbox 1.8 for Outlook on the web and new Outlook on Windows ]

Minimum permission level: read/write item

Applicable Outlook mode: Message Compose

Important:

This method isn't supported in Outlook on iOS or Android. For more information on supported APIs in Outlook mobile, see Outlook JavaScript APIs supported in Outlook on mobile devices.
In recent builds of classic Outlook on Windows, a bug was introduced that incorrectly appends an Authorization: Bearer header to this action (whether using this API or the Outlook UI). To work around this issue, use the addFileAttachmentFromBase64 API introduced with requirement set 1.8.
The URI of the file to be attached must support caching in production. The server hosting the image shouldn't return a Cache-Control header that specifies no-cache, no-store, or similar options in the HTTP response. However, when you're developing the add-in and making changes to files, caching can prevent you from seeing your changes. We recommend using Cache-Control headers during development.
You can use the same URI with the removeAttachmentAsync method to remove the attachment in the same session.

Errors:

AttachmentSizeExceeded: The attachment is larger than allowed.
FileTypeNotSupported: The attachment has an extension that is not allowed.
NumberOfAttachmentsExceeded: The message or appointment has too many attachments.

addItemAttachmentAsync(itemId, attachmentName, options, callback)

Adds an Exchange item, such as a message, as an attachment to the message or appointment.

The addItemAttachmentAsync method attaches the item with the specified Exchange identifier to the item in the compose form. If you specify a callback function, the method is called with one parameter, asyncResult, which contains either the attachment identifier or a code that indicates any error that occurred while attaching the item. You can use the options parameter to pass state information to the callback function, if needed.

You can subsequently use the identifier with the removeAttachmentAsync method to remove the attachment in the same session.

If your Office Add-in is running in Outlook on the web or new Outlook on Windows, the addItemAttachmentAsync method can attach items to items other than the item that you are editing. However, this isn't supported and isn't recommended.

addItemAttachmentAsync(itemId: any, attachmentName: string, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<string>) => void): void;

Parameters

itemId: any

The Exchange identifier of the item to attach. The maximum length is 100 characters.

attachmentName: string

The name of the attachment that is shown while the attachment is uploading. The maximum length is 255 characters.

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. On success, the attachment identifier will be provided in the asyncResult.value property. If adding the attachment fails, the asyncResult object will contain an Error object that provides a description of the error.

Returns

void

Remarks

[ API set: Mailbox 1.1 ]

Minimum permission level: read/write item

Applicable Outlook mode: Message Compose

Errors:

NumberOfAttachmentsExceeded: The message or appointment has too many attachments.

Examples

// The following example adds an existing Outlook item as an attachment
// with the name "My Attachment".
function addAttachment() {
    // EWS ID of item to attach (shortened for readability).
    const itemId = "AAMkADI1...AAA=";

    // The values in asyncContext can be accessed in the callback.
    const options = { asyncContext: { var1: 1, var2: 2 } };

    Office.context.mailbox.item.addItemAttachmentAsync(itemId, "My Attachment", options, (result) => {
        if (result.status === Office.AsyncResultStatus.Failed) {
            console.error("Failed to add attachment: " + result.error.message);
            return;
        }

        console.log("Attachment added successfully.");
        console.log("var1: " + result.asyncContext.var1);
        console.log("var2: " + result.asyncContext.var2);
    });
}

addItemAttachmentAsync(itemId, attachmentName, callback)

Adds an Exchange item, such as a message, as an attachment to the message or appointment.

You can subsequently use the identifier with the removeAttachmentAsync method to remove the attachment in the same session.

addItemAttachmentAsync(itemId: any, attachmentName: string, callback?: (asyncResult: Office.AsyncResult<string>) => void): void;

Parameters

itemId: any

The Exchange identifier of the item to attach. The maximum length is 100 characters.

attachmentName: string

The name of the attachment that is shown while the attachment is uploading. The maximum length is 255 characters.

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. On success, the attachment identifier will be provided in the asyncResult.value property. If adding the attachment fails, the asyncResult object will contain an Error object that provides a description of the error.

Returns

void

Remarks

[ API set: Mailbox 1.1 ]

Minimum permission level: read/write item

Applicable Outlook mode: Message Compose

Errors:

NumberOfAttachmentsExceeded: The message or appointment has too many attachments.

getSelectedDataAsync(coercionType, options, callback)

Asynchronously returns selected data from the subject or body of a message.

If there is no selection but the cursor is in the body or subject, the method returns an empty string for the selected data. If a field other than the body or subject is selected, the method returns the InvalidSelection error.

To access the selected data from the callback function, call asyncResult.value.data. To access the source property that the selection comes from, call asyncResult.value.sourceProperty, which will be either body or subject.

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

Parameters

coercionType: Office.CoercionType | string

Requests a format for the data. If Text, the method returns the plain text as a string, removing any HTML tags present. If Html, the method returns the selected text, whether it is plaintext or HTML.

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

When the method completes, the function passed in the callback parameter is called with a single parameter of type Office.AsyncResult.

Returns

void

The selected data as a string with format determined by coercionType.

Remarks

[ API set: Mailbox 1.2 ]

Minimum permission level: read item

Applicable Outlook mode: Message Compose

Examples

// Get selected data.
Office.context.mailbox.item.getSelectedDataAsync(Office.CoercionType.Text, { option1: "option1"}, getCallback);

function getCallback(asyncResult) {
    const text = asyncResult.value.data;
    const prop = asyncResult.value.sourceProperty;

    console.log(`Selected text in ${prop}: ${text}`);
}

getSelectedDataAsync(coercionType, callback)

Asynchronously returns selected data from the subject or body of a message.

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

Parameters

coercionType: Office.CoercionType | string

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

When the method completes, the function passed in the callback parameter is called with a single parameter of type Office.AsyncResult.

Returns

void

The selected data as a string with format determined by coercionType.

Remarks

[ API set: Mailbox 1.2 ]

Minimum permission level: read item

Applicable Outlook mode: Message Compose

Examples

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

Office.context.mailbox.item.getSelectedDataAsync(Office.CoercionType.Text, function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    const text = asyncResult.value.data;
    const prop = asyncResult.value.sourceProperty;
    console.log("Selected text in " + prop + ": " + text);
  } else {
    console.error(asyncResult.error);
  }
});

loadCustomPropertiesAsync(callback, userContext)

Asynchronously loads custom properties for this add-in on the selected item.

Custom properties are stored as key-value pairs on a per-app, per-item basis. This method returns a CustomProperties object in the callback, which provides methods to access the custom properties specific to the current item and the current add-in. Custom properties aren't encrypted on the item, so this shouldn't be used as secure storage.

The custom properties are provided as a CustomProperties object in the asyncResult.value property. This object can be used to get, set, save, and remove custom properties from the mail item.

loadCustomPropertiesAsync(callback: (asyncResult: Office.AsyncResult<CustomProperties>) => void, userContext?: any): void;

Parameters

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

When the method completes, the function passed in the callback parameter is called with a single parameter of type Office.AsyncResult.

userContext: any

Optional. Developers can provide any object they wish to access in the callback function. This object can be accessed by the asyncResult.asyncContext property in the callback function.

Returns

void

Remarks

[ API set: Mailbox 1.1 ]

To learn more about custom properties, see Get and set add-in metadata for an Outlook add-in.

Minimum permission level: read item

Applicable Outlook mode: Message Compose

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/15-item-custom-properties/load-set-get-save.yaml

Office.context.mailbox.item.loadCustomPropertiesAsync((result) => {
  if (result.status === Office.AsyncResultStatus.Failed) {
    console.error(`loadCustomPropertiesAsync failed with message ${result.error.message}`);
    return;
  }

  customProps = result.value;
  console.log("Loaded the CustomProperties object.");
});

removeAttachmentAsync(attachmentId, options, callback)

Removes an attachment from a message or appointment.

The removeAttachmentAsync method removes the attachment with the specified identifier from the item. As a best practice, you should use the attachment identifier to remove an attachment only if the same mail app has added that attachment in the same session. In Outlook on the web, on mobile devices, and in new Outlook on Windows, the attachment identifier is valid only within the same session. A session is over when the user closes the app, or if the user starts composing an inline form then subsequently pops out the form to continue in a separate window.

removeAttachmentAsync(attachmentId: string, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameters

attachmentId: string

The identifier of the attachment to remove. The maximum string length of the attachmentId is 200 characters in Outlook on the web and on Windows (new and classic).

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

Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type Office.AsyncResult. If removing the attachment fails, the asyncResult.error property will contain an error code with the reason for the failure.

Returns

void

Remarks

[ API set: Mailbox 1.1 ]

Minimum permission level: read/write item

Applicable Outlook mode: Message Compose

Important*: The removeAttachmentAsync method doesn't remove inline attachments from a mail item. To remove an inline attachment, first get the item's body, then remove any references of the attachment from its contents. Use the Office.Body APIs to get and set the body of an item.

Errors:

InvalidAttachmentId: The attachment identifier does not exist.

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/40-attachments/attachments-compose.yaml

Office.context.mailbox.item.removeAttachmentAsync(
  $("#attachmentId")
    .val()
    .toString(),
  (result) => {
    if (result.status === Office.AsyncResultStatus.Failed) {
      console.error(result.error.message);
      return;
    }

    console.log(`Attachment removed successfully.`);
  }
);

removeAttachmentAsync(attachmentId, callback)

Removes an attachment from a message or appointment.

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

Parameters

attachmentId: string

The identifier of the attachment to remove. The maximum string length of the attachmentId is 200 characters in Outlook on the web and on Windows (new and classic).

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

Returns

void

Remarks

[ API set: Mailbox 1.1 ]

Minimum permission level: read/write item

Applicable Outlook mode: Message Compose

Errors:

InvalidAttachmentId: The attachment identifier does not exist.

setSelectedDataAsync(data, options, callback)

Asynchronously inserts data into the body or subject of a message.

The setSelectedDataAsync method inserts the specified string at the cursor location in the subject or body of the item, or, if text is selected in the editor, it replaces the selected text. If the cursor is not in the body or subject field, an error is returned. 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 data to be inserted. Data is not to exceed 1,000,000 characters. If more than 1,000,000 characters are passed in, an ArgumentOutOfRange exception is thrown.

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: If text, the current style is applied in Outlook on the web, on Windows (new and classic), and on Mac. If the field is an HTML editor, only the text data is inserted, even if the data is HTML. If the data is HTML and the field supports HTML (the subject doesn't), the current style is applied in Outlook on the web and new Outlook on Windows. The default style is applied in Outlook on Windows (classic) and on Mac. If the field is a text field, an InvalidDataFormat error is returned. If coercionType is not set, the result depends on the field: if the field is HTML then HTML is used; if the field is text, then plain text is used.

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.

Returns

void

Remarks

[ API set: Mailbox 1.2 ]

Minimum permission level: read/write item

Applicable Outlook mode: Message Compose

Errors:

InvalidAttachmentId: The attachment identifier does not exist.

Examples

Office.context.mailbox.item.setSelectedDataAsync("<b>Hello World!</b>", { coercionType : "html" });

Office.context.mailbox.item.setSelectedDataAsync("Hello World!");

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/90-other-item-apis/set-selected-data.yaml

Office.context.mailbox.item.setSelectedDataAsync("Replaced", function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    console.log("Selected text has been updated successfully.");
  } else {
    console.error(asyncResult.error);
  }
});

setSelectedDataAsync(data, callback)

Asynchronously inserts data into the body or subject of a message.

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

Parameters

data: string

The data to be inserted. Data is not to exceed 1,000,000 characters. If more than 1,000,000 characters are passed in, an ArgumentOutOfRange exception is thrown.

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.

Returns

void

Remarks

[ API set: Mailbox 1.2 ]

Minimum permission level: read/write item

Applicable Outlook mode: Message Compose

Errors:

InvalidAttachmentId: The attachment identifier does not exist.

Share via

Office.MessageCompose interface

Properties

Methods

Property Details

bcc

Property Value

Remarks

Examples

body

Property Value

Remarks

Examples

cc

Property Value

Remarks

Examples

conversationId

Property Value

Remarks

Examples

itemType

Property Value

Remarks

Examples

subject

Property Value

Remarks

Examples

to

Property Value

Remarks

Examples

Method Details

addFileAttachmentAsync(uri, attachmentName, options, callback)

Parameters

Returns

Remarks

Examples

addFileAttachmentAsync(uri, attachmentName, callback)

Parameters

Returns

Remarks

addItemAttachmentAsync(itemId, attachmentName, options, callback)

Parameters

Returns

Remarks

Examples

addItemAttachmentAsync(itemId, attachmentName, callback)

Parameters

Returns

Remarks

getSelectedDataAsync(coercionType, options, callback)

Parameters

Returns

Remarks

Examples

getSelectedDataAsync(coercionType, callback)

Parameters

Returns

Remarks

Examples

loadCustomPropertiesAsync(callback, userContext)

Parameters

Returns

Remarks

Examples

removeAttachmentAsync(attachmentId, options, callback)

Parameters

Returns

Remarks

Examples

removeAttachmentAsync(attachmentId, callback)

Parameters

Returns

Remarks

setSelectedDataAsync(data, options, callback)

Parameters

Returns

Remarks