Office.LoadedMessageRead interface

Gets the item's attachments as an array.

attachments: AttachmentDetails[];

Property Value

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.

Gets the item's body and its format.

body: Body;

Property Value

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.

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

categories: Categories;

Property Value

Remarks

[ API set: Mailbox 1.8 ]

Minimum permission level: read item

Applicable Outlook mode: Message Read

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

Remarks

Minimum permission level: read item

Applicable Outlook mode: Message Read

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

Remarks

Minimum permission level: read item

Applicable Outlook mode: Message Read

Gets the date and time that an item was created.

dateTimeCreated: Date;

Property Value

Remarks

Minimum permission level: read item

Applicable Outlook mode: Message Read

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

dateTimeModified: Date;

Property Value

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.

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

Remarks

Minimum permission level: read item

Applicable Outlook mode: Message Read

Gets the email address of the sender of a message.

The from property returns an EmailAddressDetails object.

from: EmailAddressDetails;

Property Value

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.

Gets the internet message identifier of a message.

internetMessageId: string;

Property Value

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.

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

itemClass: string;

Property Value

Remarks

Minimum permission level: read item

Applicable Outlook mode: Message Read

Important:

The following table lists the default item classes for messages.

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

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

itemId: string;

Property Value

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.

Gets the type of item that an instance represents.

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

itemType: MailboxEnums.ItemType | string;

Property Value

Remarks

Minimum permission level: read item

Applicable Outlook mode: Message Read

Gets the location of a meeting request.

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

location: string;

Property Value

Remarks

Minimum permission level: read item

Applicable Outlook mode: Message Read

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

Remarks

Minimum permission level: read item

Applicable Outlook mode: Message Read

Gets the notification messages of the item.

notificationMessages: NotificationMessages;

Property Value

Remarks

[ API set: Mailbox 1.3 ]

Minimum permission level: read item

Applicable Outlook mode: Message Read

Important:

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

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

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.

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

sender: EmailAddressDetails;

Property Value

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.

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

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

seriesId: string;

Property Value

Remarks

[ API set: Mailbox 1.7 ]

Minimum permission level: read item

Applicable Outlook mode: Message 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.

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

Remarks

Minimum permission level: read item

Applicable Outlook mode: Message Read

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

Remarks

Minimum permission level: read item

Applicable Outlook mode: Message Read

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

Remarks

Minimum permission level: read item

Applicable Outlook mode: Message Read

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

Returns

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.

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

Returns

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.

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

Returns

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.

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

Returns

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.

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

Returns

Remarks

[ API set: Mailbox 1.8 ]

Minimum permission level: read item

Applicable Outlook mode: Message Read

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

Returns

Remarks

[ API set: Mailbox 1.8 ]

Minimum permission level: read item

Applicable Outlook mode: Message Read

Gets the current message in EML format encoded in Base64.

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

Parameters

Returns

Remarks

[ API set: Mailbox 1.14 ]

Minimum permission level: read item

Applicable Outlook mode: Message Read

Gets the current message in EML format encoded in Base64.

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

Parameters

Returns

Remarks

[ API set: Mailbox 1.14 ]

Minimum permission level: read item

Applicable Outlook mode: Message Read

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

Returns

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.

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

Returns

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.

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

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

Parameters

Returns

Remarks

[ API set: Mailbox 1.8 ]

Minimum permission level: read item

Applicable Outlook mode: Message Read

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

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

Parameters

Returns

Remarks

[ API set: Mailbox 1.8 ]

Minimum permission level: read item

Applicable Outlook mode: Message Read

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

getRegExMatches(): any;

Returns

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.

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

getRegExMatchesByName(name: string): string[];

Parameters

Returns

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.

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

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.

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

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

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

Parameters

Returns

Remarks

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

Minimum permission level: read item

Applicable Outlook mode: Message Read

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

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

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

Parameters

Returns

Remarks

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

Minimum permission level: read item

Applicable Outlook mode: Message Read

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

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

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

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

Parameters

Returns

Remarks

[ API set: Mailbox 1.1 ]

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

Minimum permission level: read item

Applicable Outlook mode: Message Read

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

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

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

Parameters

Returns

Remarks

[ API set: Mailbox preview ]

Minimum permission level: read/write item

Applicable Outlook mode: Message Compose

Important:

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

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

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

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

Parameters

Returns

Remarks

[ API set: Mailbox preview ]

Minimum permission level: read/write item

Applicable Outlook mode: Message Compose

Important:

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

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