Edit

Share via

Outlook extended properties overview

  • Article

Namespace: microsoft.graph

Important

APIs under the /beta version in Microsoft Graph are subject to change. Use of these APIs in production applications is not supported. To determine whether an API is available in v1.0, use the Version selector.

Caution

Outlook tasks is deprecated and stopped returning data on August 10, 2022. Update existing apps that use this feature with Outlook tasks.

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 aren't 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 Microsoft 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 aren't 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 can't use the REST API to get all the extended properties of a specific instance in one call.

id formats

You can specify id of an extended property in one of three formats:

  • As a named property, identified by the extended property type, namespace, and a string name.
  • As a named property, identified by the extended property type, namespace, and a numeric identifier.
  • In a proptag format, identified by the extended property type and a MAPI property tag.

The next two tables describe these formats as applied to single and multi-value extended properties. {type} represents the type of the value or values of the extended property. Shown in the examples are string, integer, and arrays of these types.

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 string 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 a numeric identifier.
"{type} {proptag}" "String 0x4001" Identifies a predefined property by its property tag.

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 the namespace (the GUID) and a string name.
"{type} {guid} Id {id}" "IntegerArray {8ECCC264-6880-4EBE-992F-8888D2EEAA1D} Id 0x8013" Identifies a property by the namespace (the GUID) and a numeric identifier.
"{type} {proptag}" "StringArray 0x4002" Identifies a predefined property by its property tag.

Use either of the named property formats to define a single-value or multi-value extended property as a custom property. Among the two formats, the first one that takes a string name (Name) is the preferred format for ease of reference. Named properties have their property identifiers in the 0x8000-0xfffe range.

Use the proptag format to access properties predefined by MAPI, or by a client or server, and that haven't already been exposed in Microsoft Graph. These properties have property identifiers in the 0x0001-0x7fff range. Don't try to define a custom property using the proptag format.

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.

REST API operations

Single-value extended property operations:

Multi-value extended property operations: