Office.LoadedMessageCompose interface

Gets the recipients on the Bcc (blind carbon copy) line of a message.

bcc: Recipients;

Property Value

Remarks

[ API set: Mailbox 1.1 ]

Minimum permission level: read item

Applicable Outlook mode: Message Compose

Important:

• Only the getAsync method of the Recipients object is supported.

• Depending on the Outlook client and platform, limits may apply on how many recipients you can get. For more information, see the Recipients object.

Gets the item's body and format.

body: Body;

Property Value

Remarks

[ API set: Mailbox 1.1 ]

Minimum permission level: read item

Applicable Outlook mode: Message Compose

Important: Only the getAsync and getTypeAsync methods of the Body object are supported.

Gets an object that provides methods to manage the item's categories.

categories: Categories;

Property Value

Remarks

[ API set: Mailbox 1.8 ]

Minimum permission level: read item

Applicable Outlook mode: Message Compose

Gets recipients on the Cc (carbon copy) line of a message.

cc: Recipients;

Property Value

Remarks

Minimum permission level: read item

Applicable Outlook mode: Message Compose

Important:

• Only the getAsync method of the Recipients object is supported.

• Depending on the Outlook client and platform, limits may apply on how many recipients you can get. For more information, see the Recipients object.

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.

conversationId: string;

Property Value

Remarks

Minimum permission level: read item

Applicable Outlook mode: Message Compose

Gets the delayed delivery date and time of a message.

delayDeliveryTime: DelayDeliveryTime;

Property Value

Remarks

[ API set: Mailbox 1.13 ]

Minimum permission level: read item

Applicable Outlook mode: Message Compose

Important: Only the getAsync method of the DelayDeliveryTime object is supported.

Gets the email address of the sender of a message.

from: From;

Property Value

Remarks

[ API set: Mailbox 1.7 ]

Minimum permission level: read item

Applicable Outlook mode: Message Compose

Gets the message ID of the original message being replied to by the current message.

inReplyTo: string;

Property Value

Remarks

[ API set: Mailbox 1.14 ]

Minimum permission level: read item

Applicable Outlook mode: Message Compose

Important:

• In Outlook on Windows, the inReplyTo value is maintained on all replies regardless of changes made by the user, such as changing the subject in a reply.

• The inReplyTo property returns null for new messages and meeting invites being forwarded by a user who's also the meeting organizer.

Gets the custom internet headers of a message.

To learn more, see Get and set internet headers on a message in an Outlook add-in.

internetHeaders: InternetHeaders;

Property Value

Remarks

[ API set: Mailbox 1.8 ]

Minimum permission level: read item

Applicable Outlook mode: Message Compose

Important: Only the getAsync method of the InternetHeaders object is supported.

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

Remarks

Minimum permission level: read item

Applicable Outlook mode: Message Compose

Gets the notification messages of the item.

notificationMessages: NotificationMessages;

Property Value

Remarks

[ API set: Mailbox 1.3 ]

Minimum permission level: read item

Applicable Outlook mode: Message Compose

Important:

• Only the getAllAsync method of the NotificationMessages object is supported.

Gets the sensitivity label of a message.

sensitivityLabel: SensitivityLabel;

Property Value

Remarks

[ API set: Mailbox 1.13 ]

Minimum permission level: read/write item

Applicable Outlook mode: Message Compose

Important:

• To use the sensitivity label feature in your add-in, you must have a Microsoft 365 E5 subscription.

• Only the getAsync method of the SensitivityLabel object is supported.

To learn more about how to manage sensitivity labels in your add-in, see Manage the sensitivity label of your message or appointment in compose mode.

Gets the ID of the series that an instance belongs to.

In Outlook on the web and on Windows (new and classic), the seriesId returns the Exchange Web Services (EWS) ID of the parent (series) item that this item belongs to.

seriesId: string;

Property Value

Remarks

[ API set: Mailbox 1.7 ]

Minimum permission level: read item

Applicable Outlook mode: Message Compose

Important: The identifier returned by the seriesId property is the same as the Exchange Web Services item identifier. The seriesId property isn't identical to the Outlook IDs used by the Outlook REST API. Before making REST API calls using this value, it should be converted using Office.context.mailbox.convertToRestId. For more details, see Use the Outlook REST APIs from an Outlook add-in.

The seriesId property returns null for items that don't have parent items such as single appointments, series items, or meeting requests and returns undefined for any other items that aren't meeting requests.

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

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

subject: Subject;

Property Value

Remarks

Minimum permission level: read item

Applicable Outlook mode: Message Compose

Important: Only the getAsync method of the Subject object is supported.

Gets the recipients on the To line of a message. 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.

to: Recipients;

Property Value

Remarks

Minimum permission level: read item

Applicable Outlook mode: Message Compose

Important:

• Only the getAsync method of the Recipients object is supported.

• Depending on the Outlook client and platform, limits may apply on how many recipients you can get. For more information, see the Recipients object.

Gets an attachment from a message or appointment and returns it as an AttachmentContent object.

The getAttachmentContentAsync method gets the attachment with the specified identifier from the item. As a best practice, you should get the attachment's identifier from a getAttachmentsAsync call, then in the same session, use that identifier to retrieve the attachment. In Outlook on the web and 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.

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

Parameters

Returns

Remarks

[ API set: Mailbox 1.8 ]

Minimum permission level: read item

Applicable Outlook mode: Message Compose

Errors:

• AttachmentTypeNotSupported: The attachment type isn't supported. Unsupported types include embedded images in Rich Text Format, or item attachment types other than email or calendar items (such as a contact or task item).

• InvalidAttachmentId: The attachment identifier does not exist.

Gets an attachment from a message or appointment and returns it as an AttachmentContent object.

The getAttachmentContentAsync method gets the attachment with the specified identifier from the item. As a best practice, you should get the attachment's identifier from a getAttachmentsAsync call, then in the same session, use that identifier to retrieve the attachment. In Outlook on the web and 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.

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

Parameters

Returns

Remarks

[ API set: Mailbox 1.8 ]

Minimum permission level: read item

Applicable Outlook mode: Message Compose

Errors:

• AttachmentTypeNotSupported: The attachment type isn't supported. Unsupported types include embedded images in Rich Text Format, or item attachment types other than email or calendar items (such as a contact or task item).

• InvalidAttachmentId: The attachment identifier does not exist.

Gets the item's attachments as an array.

getAttachmentsAsync(options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<AttachmentDetailsCompose[]>) => void): void;

Parameters

Returns

Remarks

[ API set: Mailbox 1.8 ]

Minimum permission level: read item

Applicable Outlook mode: Message Compose

Gets the item's attachments as an array.

getAttachmentsAsync(callback?: (asyncResult: Office.AsyncResult<AttachmentDetailsCompose[]>) => void): void;

Parameters

Returns

Remarks

[ API set: Mailbox 1.8 ]

Minimum permission level: read item

Applicable Outlook mode: Message Compose

Specifies the type of message compose and its coercion type. The message can be new, or a reply or forward. The coercion type can be HTML or plain text.

getComposeTypeAsync(options: Office.AsyncContextOptions, callback: (asyncResult: Office.AsyncResult<any>) => void): void;

Parameters

Returns

An object with ComposeType and CoercionType enum values for the message item.

Remarks

[ API set: Mailbox 1.10 ]

Minimum permission level: read item

Applicable Outlook mode: Message Compose

Specifies the type of message compose and its coercion type. The message can be new, or a reply or forward. The coercion type can be HTML or plain text.

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

Parameters

Returns

An object with ComposeType and CoercionType enum values for the message item.

Remarks

[ API set: Mailbox 1.10 ]

Minimum permission level: read item

Applicable Outlook mode: Message Compose

Gets the Base64-encoded position of the current message in a conversation thread.

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

Parameters

Returns

Remarks

[ API set: Mailbox 1.14 ]

Minimum permission level: read item

Applicable Outlook mode: Message Compose

Tip: You can use the conversation index to locate a message in a conversation thread. Then, use its contents to provide context for the current message being composed.

Gets the Base64-encoded position of the current message in a conversation thread.

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

Parameters

Returns

Remarks

[ API set: Mailbox 1.14 ]

Minimum permission level: read item

Applicable Outlook mode: Message Compose

Tip: You can use the conversation index to locate a message in a conversation thread. Then, use its contents to provide context for the current message being composed.

Gets initialization data passed when the add-in is activated by an actionable message.

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

Parameters

Returns

Remarks

[ API set: Mailbox 1.8 ]

Minimum permission level: read item

Applicable Outlook mode: Message Compose

Gets initialization data passed when the add-in is activated by an actionable message.

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

Parameters

Returns

Remarks

[ API set: Mailbox 1.8 ]

Minimum permission level: read item

Applicable Outlook mode: Message Compose

Gets the Exchange Web Services item class of the selected message.

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

Parameters

Returns

Remarks

[ API set: Mailbox 1.14 ]

Minimum permission level: read item

Applicable Outlook mode: Message Compose

Important:

The following table lists the default message classes.

Gets the Exchange Web Services item class of the selected message.

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

Parameters

Returns

Remarks

[ API set: Mailbox 1.14 ]

Minimum permission level: read item

Applicable Outlook mode: Message Compose

Important:

The following table lists the default message classes.

Asynchronously gets the Exchange Web Services (EWS) item identifier of a saved item.

When invoked, this method returns the item ID via the callback function.

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

Parameters

Returns

Remarks

[ API set: Mailbox 1.8 ]

Minimum permission level: read item

Applicable Outlook mode: Message Compose

Important:

• The item ID returned isn't identical to the Outlook Entry ID or the ID used by the Outlook REST API. Before making REST API calls using this value, it should be converted using Office.context.mailbox.convertToRestId.

• If your add-in calls getItemIdAsync on an item in compose mode (for example, to get an itemId to use with EWS or the REST API), be aware that when Outlook is in cached mode, it may take some time before the item is synced to the server. Until the item is synced, the itemId isn't recognized and using it returns an error.

Errors:

• ItemNotSaved: The ID can't be retrieved until the item is saved.

Asynchronously gets the ID of a saved item.

When invoked, this method returns the item ID via the callback function.

Note: If your add-in calls getItemIdAsync on an item in compose mode (for example, to get an itemId to use with EWS or the REST API), be aware that when Outlook is in cached mode, it may take some time before the item is synced to the server. Until the item is synced, the itemId isn't recognized and using it returns an error.

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

Parameters

Returns

Remarks

[ API set: Mailbox 1.8 ]

Minimum permission level: read item

Applicable Outlook mode: Message Compose

Errors:

• ItemNotSaved: The ID can't be retrieved until the item is saved.

Gets the properties of an appointment or message in a shared folder or shared mailbox.

For more information around using this API, see Enable shared folders and shared mailbox scenarios in an Outlook add-in.

getSharedPropertiesAsync(options: Office.AsyncContextOptions, callback: (asyncResult: Office.AsyncResult<SharedProperties>) => void): void;

Parameters

Returns

Remarks

[ API set: Mailbox 1.8 for shared folder support, Mailbox 1.13 for shared mailbox support ]

Minimum permission level: read item

Applicable Outlook mode: Message Compose

Important: In Message Compose mode, this API isn't supported in Outlook on the web or on Windows (new and classic) unless the following conditions are met.

a. Delegate access/Shared folders

1. The mailbox owner starts a message. This can be a new message, a reply, or a forward.

2. They save the message then move it from their own Drafts folder to a folder shared with the delegate.

3. The delegate opens the draft from the shared folder then continues composing.

b. Shared mailbox (applies to classic Outlook on Windows only)

1. The shared mailbox user starts a message. This can be a new message, a reply, or a forward.

2. They save the message then move it from their own Drafts folder to a folder in the shared mailbox.

3. Another shared mailbox user opens the draft from the shared mailbox then continues composing.

The message is now in a shared context and add-ins that support these shared scenarios can get the item's shared properties. After the message has been sent, it's usually found in the sender's Sent Items folder.

Gets the properties of an appointment or message in a shared folder or shared mailbox.

For more information around using this API, see Enable shared folders and shared mailbox scenarios in an Outlook add-in.

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

Parameters

Returns

Remarks

[ API set: Mailbox 1.8 for shared folder support, Mailbox 1.13 for shared mailbox support ]

Minimum permission level: read item

Applicable Outlook mode: Message Compose

Important: In Message Compose mode, this API isn't supported in Outlook on the web or on Windows (new and classic) unless the following conditions are met.

a. Delegate access/Shared folders

1. The mailbox owner starts a message. This can be a new message, a reply, or a forward.

2. They save the message then move it from their own Drafts folder to a folder shared with the delegate.

3. The delegate opens the draft from the shared folder then continues composing.

b. Shared mailbox (applies to Outlook on Windows only)

1. The shared mailbox user starts a message. This can be a new message, a reply, or a forward.

2. They save the message then move it from their own Drafts folder to a folder in the shared mailbox.

3. Another shared mailbox user opens the draft from the shared mailbox then continues composing.

The message is now in a shared context and add-ins that support these shared scenarios can get the item's shared properties. After the message has been sent, it's usually found in the sender's Sent Items folder.

Gets if the client signature is enabled.

In Outlook on Windows (classic), the API call returns true if the default signature for new messages, replies, or forwards is set to a template for the sending Outlook account. In Outlook on the web and new Outlook on Windows, the API call returns true if the signature is enabled for compose types newMail, reply, or forward. If the settings are set to "(none)" in Outlook on Windows (classic) or are disabled in Outlook on the web or new Outlook on Windows, the API call returns false.

isClientSignatureEnabledAsync(options: Office.AsyncContextOptions, callback: (asyncResult: Office.AsyncResult<boolean>) => void): void;

Parameters

Returns

Remarks

[ API set: Mailbox 1.10 ]

Minimum permission level: read item

Applicable Outlook mode: Message Compose

Gets if the client signature is enabled.

In Outlook on Windows (classic), the API call returns true if the default signature for new messages, replies, or forwards is set to a template for the sending Outlook account. In Outlook on the web and new Outlook on Windows, the API call returns true if the signature is enabled for compose types newMail, reply, or forward. If the settings are set to "(none)" in Outlook on Windows (classic) or are disabled in Outlook on the web or new Outlook on Windows, the API call returns false.

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

Parameters

Returns

Remarks

[ API set: Mailbox 1.10 ]

Minimum permission level: read item

Applicable Outlook mode: Message Compose

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 custom properties from the mail item.

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

Parameters

Returns

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

Asynchronously saves the current message as a draft.

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

Parameters

Returns

Remarks

[ API set: Mailbox 1.3 ]

Minimum permission level: read/write item

Applicable Outlook mode: Message Compose

Important:

• In Outlook on the web, new Outlook on Windows, or classic Outlook on Windows in online mode (non-cached mode), the item is saved to the server. In Outlook in cached mode, the item is saved to the local cache.

• When working with HTML-formatted content, it's important to note that the Outlook client may modify the content. This means that subsequent calls to methods like Body.getAsync, Body.setAsync, and even saveAsync may not result in the same content.

• The identifier returned is the same as the Exchange Web Services (EWS) item identifier. The item ID returned isn't identical to the Outlook Entry ID or the ID used by the Outlook REST API. Before making REST API calls using this value, it should be converted using Office.context.mailbox.convertToRestId.

• If your add-in calls saveAsync on an item in compose mode in order to get an item ID to use with EWS or the REST API, be aware that when Outlook is in cached mode, it may take some time before the item is actually synced to the server. Until the item is synced, using the item ID will return an error.

• In Outlook on the web and new Outlook on Windows, the mailbox account to which a draft is saved varies when saveAsync is called on a message that will be sent from a shared mailbox account. If the sender creates a new message from their personal mailbox and selects the shared mailbox account in the From field, saveAsync saves the draft to the Drafts folder of the user's personal mailbox. If the sender opens the shared mailbox account in a separate browser tab (through the Open another mailbox option, for example) and creates a new message there, saveAsync saves the draft to the Drafts folder of the shared mailbox.

Errors:

• InvalidAttachmentId: The attachment identifier does not exist.

Asynchronously saves the current message as a draft.

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

Parameters

Returns

Remarks

[ API set: Mailbox 1.3 ]

Minimum permission level: read/write item

Applicable Outlook mode: Message Compose

Important:

• In Outlook on the web, new Outlook on Windows, or classic Outlook on Windows in online mode (non-cached mode), the item is saved to the server. In Outlook in cached mode, the item is saved to the local cache.

• When working with HTML-formatted content, it's important to note that the Outlook client may modify the content. This means that subsequent calls to methods like Body.getAsync, Body.setAsync, and even saveAsync may not result in the same content.

• The identifier returned is the same as the Exchange Web Services (EWS) item identifier. The item ID returned isn't identical to the Outlook Entry ID or the ID used by the Outlook REST API. Before making REST API calls using this value, it should be converted using Office.context.mailbox.convertToRestId.

• If your add-in calls saveAsync on an item in compose mode in order to get an item ID to use with EWS or the REST API, be aware that when Outlook is in cached mode, it may take some time before the item is actually synced to the server. Until the item is synced, using the item ID will return an error.

• In Outlook on the web and new Outlook on Windows, the mailbox account to which a draft is saved varies when saveAsync is called on a message that will be sent from a shared mailbox account. If the sender creates a new message from their personal mailbox and selects the shared mailbox account in the From field, saveAsync saves the draft to the Drafts folder of the user's personal mailbox. If the sender opens the shared mailbox account in a separate browser tab (through the Open another mailbox option, for example) and creates a new message there, saveAsync saves the draft to the Drafts folder of the shared mailbox.

Errors:

• InvalidAttachmentId: The attachment identifier does not exist.

When multiple mail items are selected, closes the currently loaded item, so that another selected mail item can be loaded for processing.

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

Parameters

Returns

Remarks

[ API set: Mailbox preview ]

Minimum permission level: read/write item

Applicable Outlook mode: Message Compose

Important:

• To learn more about processing multiple selected messages, see Activate your Outlook add-in on multiple messages.

• When a selected mail item is loaded using loadItemByIdAsync, you must call unloadAsync after processing on it. This must be done before calling loadItemByIdAsync on another selected item.

When multiple mail items are selected, closes the currently loaded item, so that another selected mail item can be loaded for processing.

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

Parameters

Returns

Remarks

[ API set: Mailbox preview ]

Minimum permission level: read/write item

Applicable Outlook mode: Message Compose

Important:

• To learn more about processing multiple selected messages, see Activate your Outlook add-in on multiple messages.

• When a selected mail item is loaded using loadItemByIdAsync, you must call unloadAsync after processing on it. This must be done before calling loadItemByIdAsync on another selected item.