Edit

Share via

Office.LoadedMessageRead interface

Package:
outlook

Represents a message in read mode that's currently loaded. A LoadedMessageRead object is returned when Office.context.mailbox.loadItemByIdAsync is called on a message in read mode.

Remarks

[ API set: Mailbox 1.15 ]

Minimum permission level: read/write item

Applicable Outlook mode: Message Read

Important:

  • When implementing the item multi-select feature, determine if you can already access the required properties of the selected item through the Office.context.mailbox.getSelectedItemsAsync call. If you can, you don't need to call loadItemByIdAsync.

  • Only one mail item can be loaded at a time. When you implement loadItemByIdAsync, you must call unloadAsync after processing the item. This must be done before calling loadItemByIdAsync on another item.

Examples

// Gets the sender's email address of each selected message.
async function getSenderEmailAddress(item) {
    const itemId = item.itemId;
    await new Promise((resolve) => {
        Office.context.mailbox.loadItemByIdAsync(itemId, (result) => {
            if (result.status === Office.AsyncResultStatus.Failed) {
                console.log(result.error.message);
                return;
            }

            const loadedItem = result.value;
            const sender = loadedItem.from.emailAddress;
            console.log(sender);

            // Unload the current message before processing another selected message.
            loadedItem.unloadAsync((asyncResult) => {
                if (asyncResult.status === Office.AsyncResultStatus.Failed) {
                    console.log(asyncResult.error.message);
                    return;
                }

                resolve();
            });
        });
    });
}

Properties

attachments

Gets the item's attachments as an array.
body

Gets the item's body and its format.
categories

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

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

The cc property returns an array that contains an EmailAddressDetails object for each recipient listed on the Cc line of the message. The maximum number of recipients returned varies per Outlook client.

  • classic Windows: 500 recipients

  • Web browser, new Outlook: 20 recipients (collapsed view), 500 recipients (expanded view)
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.
dateTimeCreated

Gets the date and time that an item was created.
dateTimeModified

Gets the date and time that an item was last modified.
end

Gets the date and time that the appointment is to end.

The end property is a Date object expressed as a Coordinated Universal Time (UTC) date and time value. You can use the convertToLocalClientTime method to convert the end property value to the client's local date and time.

When you use the Time.setAsync method to set the end time, you should use the convertToUtcClientTime method to convert the local time on the client to UTC for the server.
from

Gets the email address of the sender of a message.

The from property returns an EmailAddressDetails object.
internetMessageId

Gets the internet message identifier of a message.
itemClass

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

Gets the Exchange Web Services item identifier for the current item.
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.
location

Gets the location of a meeting request.

The location property returns a string that contains the location of the appointment.
normalizedSubject

Gets the subject of an item, with all prefixes removed (including RE: and FWD:).

The normalizedSubject property gets the subject of the item, with any standard prefixes (such as RE: and FW:) that are added by email programs. To get the subject of the item with the prefixes intact, use the subject property.
notificationMessages

Gets the notification messages of the item.
recurrence

Gets the recurrence pattern of an appointment. Gets the recurrence pattern of a meeting request. Read and compose modes for appointment items. Read mode for meeting request items.

The recurrence property returns a Recurrence object for recurring appointments or meetings requests if an item is a series or an instance in a series. null is returned for single appointments and meeting requests of single appointments. undefined is returned for messages that aren't meeting requests.
sender

Gets the email address of the sender of an email message.
seriesId

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

Gets the date and time that the appointment is to begin.

The start property is a Date object expressed as a Coordinated Universal Time (UTC) date and time value. You can use the convertToLocalClientTime method to convert the value to the client's local date and time.
subject

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.

The subject property returns a string. Use the normalizedSubject property to get the subject minus any leading prefixes such as RE: and FW:.
to

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.

The to property returns an array that contains an EmailAddressDetails object for each recipient listed on the To line of the message. The maximum number of recipients returned varies per Outlook client.

  • classic Windows: 500 recipients

  • Web browser, new Outlook: 20 recipients (collapsed view), 500 recipients (expanded view)

Methods

displayReplyAllFormAsync(formData, options, callback)

Displays a reply form that includes either the sender and all recipients of the selected message or the organizer and all attendees of the selected appointment.
displayReplyAllFormAsync(formData, callback)

Displays a reply form that includes either the sender and all recipients of the selected message or the organizer and all attendees of the selected appointment.
displayReplyFormAsync(formData, options, callback)

Displays a reply form that includes only the sender of the selected message or the organizer of the selected appointment.
displayReplyFormAsync(formData, callback)

Displays a reply form that includes only the sender of the selected message or the organizer of the selected appointment.
getAllInternetHeadersAsync(options, callback)

Gets all the internet headers for the message as a string.

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

Gets all the internet headers for the message as a string.

To learn more, see Get and set internet headers on a message in an Outlook add-in.
getAsFileAsync(options, callback)

Gets the current message in EML format encoded in Base64.
getAsFileAsync(callback)

Gets the current message in EML format encoded in Base64.
getAttachmentContentAsync(attachmentId, options, callback)

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 an item.attachments 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, callback)

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 an item.attachments 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.
getInitializationContextAsync(options, callback)

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

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

Returns string values in the selected item that match the regular expressions defined in an XML manifest file.
getRegExMatchesByName(name)

Returns string values in the selected item that match the named regular expression defined in an XML manifest file.
getSelectedRegExMatches()

Returns string values in a highlighted match that match the regular expressions defined in an XML manifest file. Highlighted matches apply to contextual add-ins.
getSharedPropertiesAsync(options, callback)

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)

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.
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 custom properties from the mail item.
unloadAsync(options, callback)

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

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

Property Details

attachments

Gets the item's attachments as an array.

attachments: AttachmentDetails[];

Property Value

Office.AttachmentDetails[]

Remarks

Minimum permission level: read item

Applicable Outlook mode: Message Read

Note: Certain types of files are blocked by Outlook due to potential security issues and are therefore not returned. For more information, see Blocked attachments in Outlook.

body

Gets the item's body and its format.

body: Body;

Property Value

Office.Body

Remarks

[ API set: Mailbox 1.1 ]

Minimum permission level: read item

Applicable Outlook mode: Message Read

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

categories

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

categories: Categories;

Property Value

Office.Categories

Remarks

[ API set: Mailbox 1.8 ]

Minimum permission level: read item

Applicable Outlook mode: Message Read

cc

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

The cc property returns an array that contains an EmailAddressDetails object for each recipient listed on the Cc line of the message. The maximum number of recipients returned varies per Outlook client.

  • classic Windows: 500 recipients

  • Web browser, new Outlook: 20 recipients (collapsed view), 500 recipients (expanded view)

cc: EmailAddressDetails[];

Property Value

Office.EmailAddressDetails[]

Remarks

Minimum permission level: read item

Applicable Outlook mode: Message Read

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.

conversationId: string;

Property Value

string

Remarks

Minimum permission level: read item

Applicable Outlook mode: Message Read

dateTimeCreated

Gets the date and time that an item was created.

dateTimeCreated: Date;

Property Value

Date

Remarks

Minimum permission level: read item

Applicable Outlook mode: Message Read

dateTimeModified

Gets the date and time that an item was last modified.

dateTimeModified: Date;

Property Value

Date

Remarks

[ API set: Mailbox 1.1 ]

Minimum permission level: read item

Applicable Outlook mode: Appointment Attendee

Important: This property isn't supported in Outlook on Android or on iOS. For more information on supported APIs in Outlook mobile, see Outlook JavaScript APIs supported in Outlook on mobile devices.

end

Gets the date and time that the appointment is to end.

The end property is a Date object expressed as a Coordinated Universal Time (UTC) date and time value. You can use the convertToLocalClientTime method to convert the end property value to the client's local date and time.

When you use the Time.setAsync method to set the end time, you should use the convertToUtcClientTime method to convert the local time on the client to UTC for the server.

end: Date;

Property Value

Date

Remarks

Minimum permission level: read item

Applicable Outlook mode: Message Read

from

Gets the email address of the sender of a message.

The from property returns an EmailAddressDetails object.

from: EmailAddressDetails;

Property Value

Office.EmailAddressDetails

Remarks

Minimum permission level: read item

Applicable Outlook mode: Message Read

Important:

  • The from and sender properties represent the same person unless the message is sent by a delegate. In that case, the from property represents the delegator, and the sender property represents the delegate.

  • The recipientType property of the EmailAddressDetails object in the from property is undefined.

internetMessageId

Gets the internet message identifier of a message.

internetMessageId: string;

Property Value

string

Remarks

Minimum permission level: read item

Applicable Outlook mode: Message Read

Important: In the Sent Items folder, the internetMessageId may not be available yet on recently sent items. In that case, consider using Exchange Web Services to get this property from the server.

itemClass

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

itemClass: string;

Property Value

string

Remarks

Minimum permission level: read item

Applicable Outlook mode: Message Read

Important:

The following table lists the default item classes for messages.

Item class Description
IPM.Note New messages and message replies
IPM.Schedule.Meeting.Request Meeting requests
IPM.Schedule.Meeting.Canceled Meeting cancellations
IPM.Schedule.Meeting.Resp.Neg Responses to decline meeting requests
IPM.Schedule.Meeting.Resp.Pos Responses to accept meeting requests
IPM.Schedule.Meeting.Resp.Tent Responses to tentatively accept meeting requests

You can create custom classes that extend a default item class. For example, IPM.Note.Contoso.

itemId

Gets the Exchange Web Services item identifier for the current item.

itemId: string;

Property Value

string

Remarks

Minimum permission level: read item

Applicable Outlook mode: Message Read

Important:

  • The itemId property isn't available in compose mode. If an item identifier is required, the Office.context.mailbox.item.saveAsync method can be used to save the item to the store, which will return the item identifier in the asyncResult.value parameter in the callback function. If the item is already saved, you can call the Office.context.mailbox.item.getItemIdAsync method instead.

  • The identifier returned by the itemId property is the same as the Exchange Web Services item identifier. The itemId property 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.

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 Read

location

Gets the location of a meeting request.

The location property returns a string that contains the location of the appointment.

location: string;

Property Value

string

Remarks

Minimum permission level: read item

Applicable Outlook mode: Message Read

normalizedSubject

Gets the subject of an item, with all prefixes removed (including RE: and FWD:).

The normalizedSubject property gets the subject of the item, with any standard prefixes (such as RE: and FW:) that are added by email programs. To get the subject of the item with the prefixes intact, use the subject property.

normalizedSubject: string;

Property Value

string

Remarks

Minimum permission level: read item

Applicable Outlook mode: Message Read

notificationMessages

Gets the notification messages of the item.

notificationMessages: NotificationMessages;

Property Value

Office.NotificationMessages

Remarks

[ API set: Mailbox 1.3 ]

Minimum permission level: read item

Applicable Outlook mode: Message Read

Important:

recurrence

Gets the recurrence pattern of an appointment. Gets the recurrence pattern of a meeting request. Read and compose modes for appointment items. Read mode for meeting request items.

The recurrence property returns a Recurrence object for recurring appointments or meetings requests if an item is a series or an instance in a series. null is returned for single appointments and meeting requests of single appointments. undefined is returned for messages that aren't meeting requests.

recurrence: Recurrence;

Property Value

Office.Recurrence

Remarks

[ API set: Mailbox 1.7 ]

Minimum permission level: read item

Applicable Outlook mode: Message Read

Important:

  • Meeting requests have an itemClass value of IPM.Schedule.Meeting.Request.

  • If the recurrence object is null, this indicates that the object is a single appointment or a meeting request of a single appointment and not a part of a series.

  • Only the propeties and the getAsync method of the Recurrence object are supported.

sender

Gets the email address of the sender of an email message.

sender: EmailAddressDetails;

Property Value

Office.EmailAddressDetails

Remarks

Minimum permission level: read item

Applicable Outlook mode: Message Read

Important:

  • The from and sender properties represent the same person unless the message is sent by a delegate. In that case, the from property represents the delegator, and the sender property represents the delegate.

  • The recipientType property of the EmailAddressDetails object in the sender property is undefined.

seriesId

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

string

Remarks

[ API set: Mailbox 1.7 ]

Minimum permission level: read item

Applicable Outlook mode: Message Read

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.

start

Gets the date and time that the appointment is to begin.

The start property is a Date object expressed as a Coordinated Universal Time (UTC) date and time value. You can use the convertToLocalClientTime method to convert the value to the client's local date and time.

start: Date;

Property Value

Date

Remarks

Minimum permission level: read item

Applicable Outlook mode: Message Read

subject

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.

The subject property returns a string. Use the normalizedSubject property to get the subject minus any leading prefixes such as RE: and FW:.

subject: string;

Property Value

string

Remarks

Minimum permission level: read item

Applicable Outlook mode: Message Read

to

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.

The to property returns an array that contains an EmailAddressDetails object for each recipient listed on the To line of the message. The maximum number of recipients returned varies per Outlook client.

  • classic Windows: 500 recipients

  • Web browser, new Outlook: 20 recipients (collapsed view), 500 recipients (expanded view)

to: EmailAddressDetails[];

Property Value

Office.EmailAddressDetails[]

Remarks

Minimum permission level: read item

Applicable Outlook mode: Message Read

Method Details

displayReplyAllFormAsync(formData, options, callback)

Displays a reply form that includes either the sender and all recipients of the selected message or the organizer and all attendees of the selected appointment.

displayReplyAllFormAsync(formData: string | ReplyFormData, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameters

formData

string | Office.ReplyFormData

A string that contains text and HTML and that represents the body of the reply form. The string is limited to 32 KB OR a ReplyFormData object that contains body or attachment data and a callback function.

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

[ API set: Mailbox 1.9 ]

Minimum permission level: read item

Applicable Outlook mode: Message Read

Important:

  • In Outlook on the web and new Outlook on Windows, the reply form is displayed as a pop-out form in the 3-column view and a pop-up form in the 2-column or 1-column view.

  • If any of the string parameters exceed their limits, displayReplyAllFormAsync throws an exception.

  • When attachments are specified in the formData.attachments parameter, Outlook attempts to download all attachments and attach them to the reply form. If any attachments fail to be added, an error is shown in the form UI. If this isn't possible, then no error message is thrown.

displayReplyAllFormAsync(formData, callback)

Displays a reply form that includes either the sender and all recipients of the selected message or the organizer and all attendees of the selected appointment.

displayReplyAllFormAsync(formData: string | ReplyFormData, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameters

formData

string | Office.ReplyFormData

A string that contains text and HTML and that represents the body of the reply form. The string is limited to 32 KB OR a ReplyFormData object that contains body or attachment data and a 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

[ API set: Mailbox 1.9 ]

Minimum permission level: read item

Applicable Outlook mode: Message Read

Important:

  • In Outlook on the web and new Outlook on Windows, the reply form is displayed as a pop-out form in the 3-column view and a pop-up form in the 2-column or 1-column view.

  • If any of the string parameters exceed their limits, displayReplyAllFormAsync throws an exception.

  • When attachments are specified in the formData.attachments parameter, Outlook attempts to download all attachments and attach them to the reply form. If any attachments fail to be added, an error is shown in the form UI. If this isn't possible, then no error message is thrown.

displayReplyFormAsync(formData, options, callback)

Displays a reply form that includes only the sender of the selected message or the organizer of the selected appointment.

displayReplyFormAsync(formData: string | ReplyFormData, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameters

formData

string | Office.ReplyFormData

A string that contains text and HTML and that represents the body of the reply form. The string is limited to 32 KB OR a ReplyFormData object that contains body or attachment data and a callback function.

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

[ API set: Mailbox 1.9 ]

Minimum permission level: read item

Applicable Outlook mode: Message Read

Important:

  • In Outlook on the web and new Outlook on Windows, the reply form is displayed as a pop-out form in the 3-column view and a pop-up form in the 2-column or 1-column view.

  • If any of the string parameters exceed their limits, displayReplyFormAsync throws an exception.

  • When attachments are specified in the formData.attachments parameter, Outlook attempts to download all attachments and attach them to the reply form. If any attachments fail to be added, an error is shown in the form UI. If this isn't possible, then no error message is thrown.

displayReplyFormAsync(formData, callback)

Displays a reply form that includes only the sender of the selected message or the organizer of the selected appointment.

displayReplyFormAsync(formData: string | ReplyFormData, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameters

formData

string | Office.ReplyFormData

A string that contains text and HTML and that represents the body of the reply form. The string is limited to 32 KB OR a ReplyFormData object that contains body or attachment data and a 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

[ API set: Mailbox 1.9 ]

Minimum permission level: read item

Applicable Outlook mode: Message Read

Important:

  • In Outlook on the web and new Outlook on Windows, the reply form is displayed as a pop-out form in the 3-column view and a pop-up form in the 2-column or 1-column view.

  • If any of the string parameters exceed their limits, displayReplyFormAsync throws an exception.

  • When attachments are specified in the formData.attachments parameter, Outlook attempts to download all attachments and attach them to the reply form. If any attachments fail to be added, an error is shown in the form UI. If this isn't possible, then no error message is thrown.

getAllInternetHeadersAsync(options, callback)

Gets all the internet headers for the message as a string.

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

getAllInternetHeadersAsync(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

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. On success, the internet headers data is provided in the asyncResult.value property as a string. Refer to RFC 2183 for the formatting information of the returned string value. If the call fails, the asyncResult.error property will contain an error code with the reason for the failure.

Returns

void

Remarks

[ API set: Mailbox 1.8 ]

Minimum permission level: read item

Applicable Outlook mode: Message Read

getAllInternetHeadersAsync(callback)

Gets all the internet headers for the message as a string.

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

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

Parameters

callback

(asyncResult: Office.AsyncResult<string>) => 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. On success, the internet headers data is provided in the asyncResult.value property as a string. Refer to RFC 2183 for the formatting information of the returned string value. If the call fails, the asyncResult.error property will contain an error code with the reason for the failure.

Returns

void

Remarks

[ API set: Mailbox 1.8 ]

Minimum permission level: read item

Applicable Outlook mode: Message Read

getAsFileAsync(options, callback)

Gets the current message in EML format encoded in Base64.

getAsFileAsync(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 Base64-encoded EML format of the message is returned in the asyncResult.value property. Any errors encountered are returned in the asyncResult.error property.

Returns

void

Remarks

[ API set: Mailbox 1.14 ]

Minimum permission level: read item

Applicable Outlook mode: Message Read

getAsFileAsync(callback)

Gets the current message in EML format encoded in Base64.

getAsFileAsync(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 Base64-encoded EML format of the message is returned in the asyncResult.value property. Any errors encountered are returned in the asyncResult.error property.

Returns

void

Remarks

[ API set: Mailbox 1.14 ]

Minimum permission level: read item

Applicable Outlook mode: Message Read

getAttachmentContentAsync(attachmentId, options, callback)

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 an item.attachments 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

attachmentId

string

The identifier of the attachment you want to get.

options
Office.AsyncContextOptions

An object literal that contains one or more of the following properties:- asyncContext: Developers can provide any object they wish to access in the callback function.

callback

(asyncResult: Office.AsyncResult<Office.AttachmentContent>) => 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. If the call fails, the asyncResult.error property will contain an error code with the reason for the failure.

Returns

void

Remarks

[ API set: Mailbox 1.8 ]

Minimum permission level: read item

Applicable Outlook mode: Message Read

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.

getAttachmentContentAsync(attachmentId, callback)

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 an item.attachments 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

attachmentId

string

The identifier of the attachment you want to get.

callback

(asyncResult: Office.AsyncResult<Office.AttachmentContent>) => 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. If the call fails, the asyncResult.error property will contain an error code with the reason for the failure.

Returns

void

Remarks

[ API set: Mailbox 1.8 ]

Minimum permission level: read item

Applicable Outlook mode: Message Read

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.

getInitializationContextAsync(options, callback)

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

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 of type Office.AsyncResult. On success, the initialization context data is provided as a string (or an empty string if there's no initialization context) in the asyncResult.value property.

Returns

void

Remarks

[ API set: Mailbox 1.8 ]

Minimum permission level: read item

Applicable Outlook mode: Message Read

getInitializationContextAsync(callback)

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

getInitializationContextAsync(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 of type Office.AsyncResult. On success, the initialization context data is provided as a string (or an empty string if there's no initialization context) in the asyncResult.value property.

Returns

void

Remarks

[ API set: Mailbox 1.8 ]

Minimum permission level: read item

Applicable Outlook mode: Message Read

getRegExMatches()

Returns string values in the selected item that match the regular expressions defined in an XML manifest file.

getRegExMatches(): any;

Returns

any

An object that contains arrays of strings that match the regular expressions defined in the manifest XML file. The name of each array is equal to the corresponding value of the RegExName attribute of the matching ItemHasRegularExpressionMatch rule or the FilterName attribute of the matching ItemHasKnownEntity rule. For an ItemHasRegularExpressionMatch rule, a matching string has to occur in the property of the item that is specified by that rule. The PropertyName simple type defines the supported properties.

Remarks

[ API set: Mailbox 1.1 ]

Minimum permission level: read item

Applicable Outlook mode: Appointment Attendee

Important:

  • Entity-based contextual Outlook add-ins are now retired. However, regular expression rules are still supported. We recommend updating your contextual add-in to use regular expression rules as an alternative solution. For guidance on how to implement these rules, see Contextual Outlook add-ins.

  • This method is used with the activation rules feature for Outlook add-ins, which isn't supported by the unified manifest for Microsoft 365.

  • If you specify an ItemHasRegularExpressionMatch rule on the body property of an item, the regular expression should further filter the body and shouldn't attempt to return the entire body of the item. Using a regular expression such as .* to obtain the entire body of an item doesn't always return the expected results. Instead, use the Body.getAsync method to retrieve the entire body.

getRegExMatchesByName(name)

Returns string values in the selected item that match the named regular expression defined in an XML manifest file.

getRegExMatchesByName(name: string): string[];

Parameters

name

string

The name of the ItemHasRegularExpressionMatch rule element that defines the filter to match.

Returns

string[]

An array that contains the strings that match the regular expression defined in the ItemHasRegularExpressionMatch rule element in the manifest XML file, with the specified RegExName element value.

Remarks

[ API set: Mailbox 1.1 ]

Minimum permission level: read item

Applicable Outlook mode: Appointment Attendee

Important:

  • Entity-based contextual Outlook add-ins are now retired. However, regular expression rules are still supported. We recommend updating your contextual add-in to use regular expression rules as an alternative solution. For guidance on how to implement these rules, see Contextual Outlook add-ins.

  • This method is used with the activation rules feature for Outlook add-ins, which isn't supported by the unified manifest for Microsoft 365.

  • If you specify an ItemHasRegularExpressionMatch rule on the body property of an item, the regular expression should further filter the body and shouldn't attempt to return the entire body of the item. Using a regular expression such as .* to obtain the entire body of an item doesn't always return the expected results. Instead, use the Body.getAsync method to retrieve the entire body.

getSelectedRegExMatches()

Returns string values in a highlighted match that match the regular expressions defined in an XML manifest file. Highlighted matches apply to contextual add-ins.

getSelectedRegExMatches(): any;

Returns

any

An object that contains arrays of strings that match the regular expressions defined in the manifest XML file. The name of each array is equal to the corresponding value of the RegExName attribute of the matching ItemHasRegularExpressionMatch rule or the FilterName attribute of the matching ItemHasKnownEntity rule. For an ItemHasRegularExpressionMatch rule, a matching string has to occur in the property of the item that is specified by that rule. The PropertyName simple type defines the supported properties.

Remarks

[ API set: Mailbox 1.6 ]

Minimum permission level: read item

Applicable Outlook mode: Message Read

Important:

  • Entity-based contextual Outlook add-ins are now retired. However, regular expression rules are still supported. We recommend updating your contextual add-in to use regular expression rules as an alternative solution. For guidance on how to implement these rules, see Contextual Outlook add-ins.

  • This method is used with the activation rules feature for Outlook add-ins, which isn't supported by the unified manifest for Microsoft 365.

  • If you specify an ItemHasRegularExpressionMatch rule on the body property of an item, the regular expression should further filter the body and shouldn't attempt to return the entire body of the item. Using a regular expression such as .* to obtain the entire body of an item doesn't always return the expected results. Instead, use the Body.getAsync method to retrieve the entire body.

getSharedPropertiesAsync(options, callback)

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

options
Office.AsyncContextOptions

An object literal that contains one or more of the following properties:- asyncContext: Developers can provide any object they wish to access in the callback function.

callback

(asyncResult: Office.AsyncResult<Office.SharedProperties>) => 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 asyncResult.value property provides the properties of the shared item.

Returns

void

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 Read

getSharedPropertiesAsync(callback)

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

callback

(asyncResult: Office.AsyncResult<Office.SharedProperties>) => 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 asyncResult.value property provides the properties of the shared item.

Returns

void

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 Read

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

Important: Only the get and getAll methods of the CustomProperties object are supported.

unloadAsync(options, callback)

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

options
Office.AsyncContextOptions

An object literal that contains the asyncContext property. Assign any object you wish to access in the callback function to the asyncContext property.

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

[ API set: Mailbox 1.15 ]

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.

unloadAsync(callback)

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

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

[ API set: Mailbox 1.15 ]

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.