Office.MessageCompose interface
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
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 |
conversation |
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 |
from | Gets the email address of the sender of a message. The |
item |
Gets the type of item that an instance represents. The |
notification |
Gets the notification messages for an item. |
series |
Gets the ID of the series that an instance belongs to. In Outlook on the web, on Windows (new and classic), and on Mac, the Note: The identifier returned by the The |
subject | Gets or sets the description that appears in the subject field of an item. The The |
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 |
Methods
add |
Adds a file to a message or appointment as an attachment. The |
add |
Adds a file to a message or appointment as an attachment. The |
add |
Adds an event handler for a supported event. Note: Events are only available with task pane implementation. For supported events, refer to the Item object model events section. |
add |
Adds an event handler for a supported event. Note: Events are only available with task pane implementation. For supported events, refer to the Item object model events section. |
add |
Adds an Exchange item, such as a message, as an attachment to the message or appointment. The You can subsequently use the identifier with the If your Office Add-in is running in Outlook on the web or new Outlook on Windows, the |
add |
Adds an Exchange item, such as a message, as an attachment to the message or appointment. The You can subsequently use the identifier with the If your Office Add-in is running in Outlook on the web or new Outlook on Windows, the |
close() | Closes the current item that is being composed. The behavior of the In Outlook on Windows (classic) and on Mac, the |
get |
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 To access the selected data from the callback function, call |
get |
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 To access the selected data from the callback function, call |
load |
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 |
remove |
Removes an attachment from a message or appointment. The |
remove |
Removes an attachment from a message or appointment. The |
remove |
Removes the event handlers for a supported event type. Note: Events are only available with task pane implementation. For supported events, refer to the Item object model events section. |
remove |
Removes the event handlers for a supported event type. Note: Events are only available with task pane implementation. For supported events, refer to the Item object model events section. |
save |
Asynchronously saves the current message as a draft. |
save |
Asynchronously saves the current message as a draft. |
set |
Asynchronously inserts data into the body or subject of a message. The |
set |
Asynchronously inserts data into the body or subject of a message. The |
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
Remarks
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
Remarks
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
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}`);
from
Gets the email address of the sender of a message.
The from
property returns a From
object that provides a method to get the from value.
from: From;
Property Value
Remarks
Minimum permission level: read item
Applicable Outlook mode: Message Compose
Important: This property is supported in Outlook on Android and on iOS. For a sample scenario, see Implement event-based activation in Outlook mobile add-ins.
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/30-recipients-and-attendees/get-from-message-compose.yaml
Office.context.mailbox.item.from.getAsync(function(asyncResult) {
if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
const msgFrom = asyncResult.value;
console.log("Message from: " + msgFrom.displayName + " (" + msgFrom.emailAddress + ")");
} else {
console.error(asyncResult.error);
}
});
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;
}
notificationMessages
Gets the notification messages for an item.
notificationMessages: NotificationMessages;
Property Value
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/35-notifications/add-getall-remove.yaml
// Adds a progress indicator to the mail item.
const id = $("#notificationId").val().toString();
const details =
{
type: Office.MailboxEnums.ItemNotificationMessageType.ProgressIndicator,
message: "Progress indicator with id = " + id
};
Office.context.mailbox.item.notificationMessages.addAsync(id, details, handleResult);
...
// Adds an informational notification to the mail item.
const id = $("#notificationId").val().toString();
const details =
{
type: Office.MailboxEnums.ItemNotificationMessageType.InformationalMessage,
message: "Non-persistent informational notification message with id = " + id,
icon: "icon1",
persistent: false
};
Office.context.mailbox.item.notificationMessages.addAsync(id, details, handleResult);
...
// Adds a persistent information notification to the mail item.
const id = $("#notificationId").val().toString();
const details =
{
type: Office.MailboxEnums.ItemNotificationMessageType.InformationalMessage,
message: "Persistent informational notification message with id = " + id,
icon: "icon1",
persistent: true
};
Office.context.mailbox.item.notificationMessages.addAsync(id, details, handleResult);
...
// Gets all the notification messages and their keys for the current mail item.
Office.context.mailbox.item.notificationMessages.getAllAsync((asyncResult) => {
if (asyncResult.status === Office.AsyncResultStatus.Failed) {
console.log(asyncResult.error.message);
return;
}
console.log(asyncResult.value);
});
...
// Replaces a notification message of a given key with another message.
const id = $("#notificationId").val().toString();
Office.context.mailbox.item.notificationMessages.replaceAsync(
id,
{
type: Office.MailboxEnums.ItemNotificationMessageType.InformationalMessage,
message: "Notification message with id = " + id + " has been replaced with an informational message.",
icon: "icon2",
persistent: false
},
handleResult);
...
// Removes a notification message from the current mail item.
const id = $("#notificationId").val().toString();
Office.context.mailbox.item.notificationMessages.removeAsync(id, handleResult);
seriesId
Gets the ID of the series that an instance belongs to.
In Outlook on the web, on Windows (new and classic), and on Mac, the seriesId
returns the Exchange Web Services (EWS) ID of the parent (series) item that this item belongs to. However, in Outlook on Android and on iOS, the seriesId returns the REST ID of the parent item.
Note: The identifier returned by the seriesId
property is the same as the Exchange Web Services item identifier. The seriesId
property is not 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 do not have parent items such as single appointments, series items, or meeting requests and returns undefined
for any other items that are not meeting requests.
seriesId: 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/50-recurrence/get-series-id.yaml
const seriesId = Office.context.mailbox.item.seriesId;
if (seriesId === undefined) {
console.log("This is a message that's not a meeting request.");
} else if (seriesId === null) {
console.log("This is a single appointment, a parent series, or a meeting request for a series or single meeting.");
} else {
console.log("This is an instance belonging to series with ID " + seriesId);
}
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
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
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
Minimum permission level: read/write item
Applicable Outlook mode: Message Compose
Important:
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, you can try using theaddFileAttachmentFromBase64
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 specifiesno-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 usingCache-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
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
Minimum permission level: read/write item
Applicable Outlook mode: Message Compose
Important:
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, you can try using theaddFileAttachmentFromBase64
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 specifiesno-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 usingCache-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.
addHandlerAsync(eventType, handler, options, callback)
Adds an event handler for a supported event. Note: Events are only available with task pane implementation.
For supported events, refer to the Item object model events section.
addHandlerAsync(eventType: Office.EventType | string, handler: any, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;
Parameters
- eventType
-
Office.EventType | string
The event that should invoke the handler.
- handler
-
any
The function to handle the event. The function must accept a single parameter, which is an object literal. The type
property on the parameter will match the eventType
parameter passed to addHandlerAsync
.
- 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, asyncResult
, which is an Office.AsyncResult
object.
Returns
void
Remarks
Minimum permission level: read item
Applicable Outlook mode: Message Compose
Examples
function myHandlerFunction(eventarg) {
if (eventarg.attachmentStatus === Office.MailboxEnums.AttachmentStatus.Added) {
const attachment = eventarg.attachmentDetails;
console.log("Event Fired and Attachment Added!");
getAttachmentContentAsync(attachment.id, options, callback);
}
}
Office.context.mailbox.item.addHandlerAsync(Office.EventType.AttachmentsChanged, myHandlerFunction, myCallback);
addHandlerAsync(eventType, handler, callback)
Adds an event handler for a supported event. Note: Events are only available with task pane implementation.
For supported events, refer to the Item object model events section.
addHandlerAsync(eventType: Office.EventType | string, handler: any, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;
Parameters
- eventType
-
Office.EventType | string
The event that should invoke the handler.
- handler
-
any
The function to handle the event. The function must accept a single parameter, which is an object literal. The type
property on the parameter will match the eventType
parameter passed to addHandlerAsync
.
- callback
-
(asyncResult: Office.AsyncResult<void>) => void
Optional. When the method completes, the function passed in the callback
parameter is called with a single parameter, asyncResult
, which is an Office.AsyncResult
object.
Returns
void
Remarks
Minimum permission level: read item
Applicable Outlook mode: Message Compose
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
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.
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, 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
Minimum permission level: read/write item
Applicable Outlook mode: Message Compose
Errors:
NumberOfAttachmentsExceeded
: The message or appointment has too many attachments.
close()
Closes the current item that is being composed.
The behavior of the close
method depends on the current state of the item being composed. If the item has unsaved changes, the client prompts the user to save, discard, or close the action.
In Outlook on Windows (classic) and on Mac, the close
method has no effect on a reply in the Reading Pane.
close(): void;
Returns
void
Remarks
Minimum permission level: restricted
Applicable Outlook mode: Message Compose
Important: In Outlook on the web and new Outlook on Windows, if the item is an appointment and it has previously been saved using saveAsync
, the user is prompted to save, discard, or cancel even if no changes have occurred since the item was last saved.
Tip: Use the closeAsync method instead of the close
method if you want your add-in to:
Automatically discard a message being composed without prompting the user with the save dialog.
Determine when a user cancels the save item dialog on a message being composed.
Close a reply in the Reading Pane or an existing draft.
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/25-item-save-and-close/close.yaml
Office.context.mailbox.item.close();
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
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.
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, 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.
- 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
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
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
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.
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, 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
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
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.
removeHandlerAsync(eventType, options, callback)
Removes the event handlers for a supported event type. Note: Events are only available with task pane implementation.
For supported events, refer to the Item object model events section.
removeHandlerAsync(eventType: Office.EventType | string, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;
Parameters
- eventType
-
Office.EventType | string
The event that should revoke the handler.
- 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, asyncResult
, which is an Office.AsyncResult
object.
Returns
void
Remarks
Minimum permission level: read item
Applicable Outlook mode: Message Compose
removeHandlerAsync(eventType, callback)
Removes the event handlers for a supported event type. Note: Events are only available with task pane implementation.
For supported events, refer to the Item object model events section.
removeHandlerAsync(eventType: Office.EventType | string, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;
Parameters
- eventType
-
Office.EventType | string
The event that should revoke the handler.
- callback
-
(asyncResult: Office.AsyncResult<void>) => void
Optional. When the method completes, the function passed in the callback
parameter is called with a single parameter, asyncResult
, which is an Office.AsyncResult
object.
Returns
void
Remarks
Minimum permission level: read item
Applicable Outlook mode: Message Compose
Examples
Office.context.mailbox.item.removeHandlerAsync(Office.EventType.ItemChanged, (asyncResult) => {
if (asyncResult.status === Office.AsyncResultStatus.Failed) {
console.error("Failed to remove event handler: " + asyncResult.error.message);
return;
}
console.log("Event handler removed successfully.");
});
saveAsync(options, callback)
Asynchronously saves the current message as a draft.
saveAsync(options: Office.AsyncContextOptions, callback: (asyncResult: Office.AsyncResult<string>) => void): void;
Parameters
- options
- Office.AsyncContextOptions
An object literal that contains one or more of the following properties:- asyncContext
: Developers can provide any object they wish to access in the callback function.
- callback
-
(asyncResult: Office.AsyncResult<string>) => void
When the method completes, the function passed in the callback
parameter is called with a single parameter, asyncResult
, which is an Office.AsyncResult
object. The EWS message ID is returned in the asyncResult.value
property.
Returns
void
Remarks
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 evensaveAsync
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
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.
saveAsync(callback)
Asynchronously saves the current message as a draft.
saveAsync(callback: (asyncResult: Office.AsyncResult<string>) => void): void;
Parameters
- callback
-
(asyncResult: Office.AsyncResult<string>) => void
When the method completes, the function passed in the callback
parameter is called with a single parameter, asyncResult
, which is an Office.AsyncResult
object. The EWS message ID is returned in the asyncResult.value
property.
Returns
void
Remarks
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 evensaveAsync
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
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.
Examples
Office.context.mailbox.item.saveAsync(
function callback(result) {
// Process the result.
});
// The following is an example of the
// `result` parameter passed to the
// callback function. The `value`
// property contains the item ID of
// the item.
{
"value": "AAMkADI5...AAA=",
"status": "succeeded"
}
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.
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
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.
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, 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
Minimum permission level: read/write item
Applicable Outlook mode: Message Compose
Errors:
InvalidAttachmentId
: The attachment identifier does not exist.
Office Add-ins