item (Mailbox requirement set 1.9)

Article
07/18/2024

Office .context .mailbox.item

item is used to access the currently selected message, meeting request, or appointment. You can determine the type of the item by using the itemType property.

Requirements

Requirement	Value
Minimum mailbox requirement set version	1.1
Minimum permission level	restricted
Applicable Outlook mode	Appointment Organizer, Appointment Attendee, Message Compose, or Message Read

Important

Android and iOS: There are limitations on when add-ins activate and which APIs are available. To learn more, refer to Add mobile support to an Outlook add-in.

Properties

Property	Minimum permission level	Details by mode	Return type	Minimum requirement set
attachments	read item	Appointment Attendee	Array.<AttachmentDetails>	1.1
		Message Read	Array.<AttachmentDetails>	1.1
bcc	read item	Message Compose	Recipients	1.1
body	read item	Appointment Organizer	Body	1.1
		Appointment Attendee	Body	1.1
		Message Compose	Body	1.1
		Message Read	Body	1.1
categories	read item	Appointment Organizer	Categories	1.8
		Appointment Attendee	Categories	1.8
		Message Compose	Categories	1.8
		Message Read	Categories	1.8
cc	read item	Message Compose	Recipients	1.1
		Message Read	Array.<EmailAddressDetails>	1.1
conversationId	read item	Message Compose	String	1.1
		Message Read	String	1.1
dateTimeCreated	read item	Appointment Attendee	Date	1.1
		Message Read	Date	1.1
dateTimeModified	read item	Appointment Attendee	Date	1.1
		Message Read	Date	1.1
end	read item	Appointment Organizer	Time	1.1
		Appointment Attendee	Date	1.1
		Message Read (Meeting Request)	Date	1.1
enhancedLocation	read item	Appointment Organizer	EnhancedLocation	1.8
		Appointment Attendee	EnhancedLocation	1.8
from	read/write item	Message Compose	From	1.7
	read item	Message Read	EmailAddressDetails	1.1
internetHeaders	read item	Message Compose	InternetHeaders	1.8
internetMessageId	read item	Message Read	String	1.1
itemClass	read item	Appointment Attendee	String	1.1
		Message Read	String	1.1
itemId	read item	Appointment Attendee	String	1.1
		Message Read	String	1.1
itemType	read item	Appointment Organizer	MailboxEnums.ItemType	1.1
		Appointment Attendee	MailboxEnums.ItemType	1.1
		Message Compose	MailboxEnums.ItemType	1.1
		Message Read	MailboxEnums.ItemType	1.1
location	read item	Appointment Organizer	Location	1.1
		Appointment Attendee	String	1.1
		Message Read (Meeting Request)	String	1.1
normalizedSubject	read item	Appointment Attendee	String	1.1
		Message Read	String	1.1
notificationMessages	read item	Appointment Organizer	NotificationMessages	1.3
		Appointment Attendee	NotificationMessages	1.3
		Message Compose	NotificationMessages	1.3
		Message Read	NotificationMessages	1.3
optionalAttendees	read item	Appointment Organizer	Recipients	1.1
		Appointment Attendee	Array.<EmailAddressDetails>	1.1
organizer	read/write item	Appointment Organizer	Organizer	1.7
	read item	Appointment Attendee	EmailAddressDetails	1.1
recurrence	read item	Appointment Organizer	Recurrence	1.7
		Appointment Attendee	Recurrence	1.7
		Message Read (Meeting Request)	Recurrence	1.7
requiredAttendees	read item	Appointment Organizer	Recipients	1.1
		Appointment Attendee	Array.<EmailAddressDetails>	1.1
sender	read item	Message Read	EmailAddressDetails	1.1
seriesId	read item	Appointment Organizer	String	1.7
		Appointment Attendee	String	1.7
		Message Compose	String	1.7
		Message Read	String	1.7
start	read item	Appointment Organizer	Time	1.1
		Appointment Attendee	Date	1.1
		Message Read (Meeting Request)	Date	1.1
subject	read item	Appointment Organizer	Subject	1.1
		Appointment Attendee	String	1.1
		Message Compose	Subject	1.1
		Message Read	String	1.1
to	read item	Message Compose	Recipients	1.1
		Message Read	Array.<EmailAddressDetails>	1.1

Methods

Method	Minimum permission level	Details by mode	Minimum requirement set
addFileAttachmentAsync(uri, attachmentName, [options], [callback])	read/write item	Appointment Organizer	1.1
		Message Compose	1.1
addFileAttachmentFromBase64Async(base64File, attachmentName, [options], [callback])	read/write item	Appointment Organizer	1.8
		Message Compose	1.8
addHandlerAsync(eventType, handler, [options], [callback])	read item	Appointment Organizer	1.7
		Appointment Attendee	1.7
		Message Compose	1.7
		Message Read	1.7
addItemAttachmentAsync(itemId, attachmentName, [options], [callback])	read/write item	Appointment Organizer	1.1
		Message Compose	1.1
close()	restricted	Appointment Organizer	1.3
		Message Compose	1.3
displayReplyAllForm(formData)	read item	Appointment Attendee	1.1
		Message Read	1.1
displayReplyAllFormAsync(formData, [options], [callback])	read item	Appointment Attendee	1.9
		Message Read	1.9
displayReplyForm(formData)	read item	Appointment Attendee	1.1
		Message Read	1.1
displayReplyFormAsync(formData, [options], [callback])	read item	Appointment Attendee	1.9
		Message Read	1.9
getAllInternetHeadersAsync([options], [callback])	read item	Message Read	1.8
getAttachmentContentAsync(attachmentId, [options], [callback])	read item	Appointment Organizer	1.8
		Appointment Attendee	1.8
		Message Compose	1.8
		Message Read	1.8
getAttachmentsAsync([options], [callback])	read item	Appointment Organizer	1.8
		Message Compose	1.8
getEntities() (deprecated)	read item	Appointment Attendee	1.1
		Message Read	1.1
getEntitiesByType(entityType) (deprecated)	restricted	Appointment Attendee	1.1
		Message Read	1.1
getFilteredEntitiesByName(name) (deprecated)	read item	Appointment Attendee	1.1
		Message Read	1.1
getInitializationContextAsync([options], [callback])	read item	Appointment Organizer	1.8
		Appointment Attendee	1.8
		Message Compose	1.8
		Message Read	1.8
getItemIdAsync([options], callback)	read item	Appointment Organizer	1.8
		Message Compose	1.8
getRegExMatches()	read item	Appointment Attendee	1.1
		Message Read	1.1
getRegExMatchesByName(name)	read item	Appointment Attendee	1.1
		Message Read	1.1
getSelectedDataAsync(coercionType, [options], callback)	read item	Appointment Organizer	1.2
		Message Compose	1.2
getSelectedEntities() (deprecated)	read item	Appointment Attendee	1.6
		Message Read	1.6
getSelectedRegExMatches()	read item	Appointment Attendee	1.6
		Message Read	1.6
getSharedPropertiesAsync([options], callback)	read item	Appointment Organizer	1.8
		Appointment Attendee	1.8
		Message Compose	1.8
		Message Read	1.8
loadCustomPropertiesAsync(callback, [userContext])	read item	Appointment Organizer	1.1
		Appointment Attendee	1.1
		Message Compose	1.1
		Message Read	1.1
removeAttachmentAsync(attachmentId, [options], [callback])	read/write item	Appointment Organizer	1.1
		Message Compose	1.1
removeHandlerAsync(eventType, [options], [callback])	read item	Appointment Organizer	1.7
		Appointment Attendee	1.7
		Message Compose	1.7
		Message Read	1.7
saveAsync([options], callback)	read/write item	Appointment Organizer	1.3
		Message Compose	1.3
setSelectedDataAsync(data, [options], callback)	read/write item	Appointment Organizer	1.2
		Message Compose	1.2

Events

You can subscribe to and unsubscribe from the following events using addHandlerAsync and removeHandlerAsync respectively.

Important

Events are only available with task pane implementation.

Event	Description	Minimum requirement set
`AppointmentTimeChanged`	The date or time of the selected appointment or series has changed.	1.7
`AttachmentsChanged`	An attachment has been added to or removed from the item.	1.8
`EnhancedLocationsChanged`	The location of the selected appointment has changed.	1.8
`RecipientsChanged`	The recipient list of the selected item or appointment location has changed.	1.7
`RecurrenceChanged`	The recurrence pattern of the selected series has changed.	1.7

Example

The following JavaScript code example shows how to access the subject property of the current item in Outlook.

// The initialize function is required for all apps.
Office.initialize = function () {
  // Checks for the DOM to load using the jQuery ready method.
  $(document).ready(function () {
    // After the DOM is loaded, app-specific code can run.
    const item = Office.context.mailbox.item;
    const subject = item.subject;
    // Continue with processing the subject of the current item,
    // which can be a message or appointment.
  });
};

Share via