Outlook extended properties overview

Extended properties allow storing custom data and specifically serve as a fallback mechanism for apps to access custom data for Outlook MAPI properties when these properties are not already exposed in the Microsoft Graph API metadata. You can use extended properties REST API to store or get such custom data in the following user resources:

Or, in the following Office 365 group resources:

Use extended properties or open extensions?

In most common scenarios, you should be able to use open extensions (represented by openTypeExtension, formerly known as Office 365 data extensions) to store and access custom data for resource instances in a user's mailbox. Use extended properties only if you need to access custom data for Outlook MAPI properties that are not already exposed in the Microsoft Graph API metadata.

Types of extended properties

Depending on whether you intend to store a single or multiple values (of the same type) in an extended property, you can create an extended property as a singleValueLegacyExtendedProperty, or multiValueLegacyExtendedProperty.

Each of these types identifies the property by its id and stores data in value.

You can use id to get a specific resource instance together with that extended property, or filter on a single-value extended property to get all the instances that have that property.

Note You cannot use the REST API to get all the extended properties of a specific instance in one call.

id Formats

When creating a single-value or multi-value extended property, you can specify id in one of two formats, based on either a string name or numeric identifier, and on the actual type of value or values of the property. Since extended properties are in most cases inter-operating with defined MAPI properties not exposed in the Microsoft Graph API metadata, for simplicity, the format you choose should reflect whether the corresponding MAPI property uses a character string or numeric value in its MAPI property identifier. You can find information about mapping an extended property to an existing MAPI property, such as the property identifier and GUID, in [MS-OXPROPS] Microsoft Corporation, "Exchange Server Protocols Master Property List".

Note After you have chosen one format for the id, you should access that extended property by only that format.

Valid id formats for single-value extended properties

Format Example Description
"{_type} {_guid} Name {_name_}" "String {8ECCC264-6880-4EBE-992F-8888D2EEAA1D} Name TestProperty" Identifies a property by the namespace (the GUID) it belongs to, and a name.
"{_type} {_guid} Id {_id_}" "Integer {8ECCC264-6880-4EBE-992F-8888D2EEAA1D} Id 0x8012" Identifies a property by the namespace (the GUID) it belongs to, and an identifier.

Valid id formats for multi-value extended properties

Format Example Description
"{_type} {_guid} Name {_name_}" "StringArray {8ECCC264-6880-4EBE-992F-8888D2EEAA1D} Name TestProperty" Identifies a property by namespace (the GUID) and name.
"{_type} {_guid} Id {_id_}" "IntegerArray {8ECCC264-6880-4EBE-992F-8888D2EEAA1D} Id 0x8013" Identifies a property by namespace (the GUID) and identifier.

REST API operations

Single-value extended property operations:

Multi-value extended property operations: