[DEPRECATED] Outlook Extended Properties REST API reference (version 2.0)

  • Article

Applies to: Exchange Online | Office 365 | Hotmail.com | Live.com | MSN.com | Outlook.com | Passport.com

Note

Version 2.0 of the Outlook REST API is deprecated.

As announced on November 17, 2020, version 2.0 of the Outlook REST API has been deprecated. The v2.0 REST endpoint will be fully decommissioned in November 2022, and the v2.0 documentation will be removed shortly afterwards. Migrate existing apps to use Microsoft Graph. See a comparison to start your migration.

The Outlook Extended Properties REST API allows apps to store custom data and provides them a fallback mechanism to access custom data for Outlook MAPI properties when these properties are not already exposed in the Outlook REST API metadata. You can use the Extended Properties API to store or get such custom data in a message, mail folder, event, calendar, contact, contact folder, task, or task folder in the signed-in user's account. The account can be on Office 365 or a Microsoft account (Hotmail.com, Live.com, MSN.com, Outlook.com, and Passport.com).

Note

For simplicity of reference, the rest of this article uses Outlook.com to include these Microsoft account domains.

Not interested in v2.0 of the API? In the table of contents on the left, go to the Office 365 REST API reference section and select the version you want.

Using the Extended Properties REST API

Extended properties or Data Extensions?

Use extended properties and this REST API only if you need to access custom data for Outlook MAPI properties that are not already exposed through the Outlook REST API metadata. For most scenarios, you should use Office 365 Data Extensions and its REST API to store and access custom data for items in the user’s mailbox. You can verify which properties the metadata exposes at https://outlook.office.com/api/{version}/$metadata, substituting {version} by v2.0, beta, etc., for the version of your choice.

Authentication

Like other Outlook REST API, for every request to the Extended Properties API, you should include a valid access token. Getting an access token requires you to have registered and identified your app, and obtained the appropriate authorization.

You can find out more about some streamlined registration and authorization options for you. Keep this in mind as you proceed with the specific operations in the Extended Properties API.

Version of API

This API has been promoted from preview to General Availability (GA) status. It is supported in the v2.0 and beta versions of the Outlook REST API.

Supported REST resources

You can create extended properties for instances of the following resources:

The resource must be in the signed-in user's mailbox in Office 365 or Outlook.com.

URL parameters

The examples in this article use the following ID placeholders in parameters of REST request URLs. You must specify the ID of the instance of the resource for which you want to create an extension.

Parameter Type Description
URL parameters
calendar_id string The calendar ID.
contact_id string The contact ID.
contactFolder_id string The contact folder ID.
event_id string The event ID.
mailFolder_id string The mail folder ID.
message_id string The message ID.
propertyId_value string A PropertyId value in one of the supported formats.
property_value string The value of an extended property.
task_id string The task ID.
taskFolder_id string The task folder ID.

See Use the Outlook REST API for more information common to all subsets of the Outlook REST API.

Overview

You can dynamically create and store data in an extended property of an entity instance. Depending on whether you intend to store single or multiple values (of the same type), you can create the extended property as a SingleValueLegacyExtendedProperty, or MultiValueLegacyExtendedProperty.

Each of these types identifies the property by its PropertyId and stores data in Value.

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

Note

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

PropertyId formats

When creating a single-value or multi-value extended property, you can specify the PropertyId 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. The following two tables describe the supported formats to specify single and multi-value extended properties. {_type_} represents the type of the value or values of the property. Shown in the examples are string, integer, and arrays of these types.

Since extended properties are in most cases inter-operating with defined MAPI properties not exposed in the Outlook REST 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 that you would need to map 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 PropertyId, you should access that extended property by only that format.

Valid PropertyId 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 PropertyId 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.

Extended property operations

Create extended property in an existing item

Create one or more extended properties for the specified instance of a supported resource. Each extended property can be single-valued or multi-valued.

PATCH https://outlook.office.com/api/v2.0/me/messages('{message_id}')
PATCH https://outlook.office.com/api/v2.0/me/events('{event_id}')
PATCH https://outlook.office.com/api/v2.0/me/contacts('{contact_id}')
PATCH https://outlook.office.com/api/v2.0/me/tasks('{task_id}')
PATCH https://outlook.office.com/api/v2.0/me/mailfolders('{mailFolder_id}')
PATCH https://outlook.office.com/api/v2.0/me/calendars('{calendar_id}')
PATCH https://outlook.office.com/api/v2.0/me/contactfolders('{contactFolder_id}')
PATCH https://outlook.office.com/api/v2.0/me/taskfolders('{taskFolder_id}')

Minimum required scope

One of the following read/write scopes corresponding to the targeted resource:

Parameter Type Description
Body parameters
SingleValueExtendedProperties Collection (SingleValueLegacyExtendedProperty) An array of one or more single-valued extended properties.
PropertyId string For each property in the SingleValueExtendedProperties collection, specify this to identify the property. It must follow one of the supported formats for single-value extended properties. Required.
Value string For each property in the SingleValueExtendedProperties collection, specify the property value. Required.
MultiValueExtendedProperties Collection (MultiValueLegacyExtendedProperty) An array of one or more multi-valued extended properties.
PropertyId string For each property in the MultiValueExtendedProperties collection, specify this to identify the property. It must follow one of the supported formats for multi-value extended properties. Required.
Value Collection(string) For each property in the MultiValueExtendedProperties collection, specify the values for that property. Required.

Sample request

The first example creates one single-value extended property for the specified message. That extended property is the only element in the SingleValueExtendedProperties array. The request body includes the following for the extended property:

  • PropertyId specifies the property type as string, the GUID, and the property named Color.
  • Value specifies Green as the value of the Color property.
PATCH https://outlook.office.com/api/v2.0/me/messages('AAMkAGE1M2_bs88AACHsLqWAAA=')

Content-Type: application/json

{
  "SingleValueExtendedProperties": [
      {
         "PropertyId":"String {66f5a359-4659-4830-9070-00047ec6ac6e} Name Color",
         "Value":"Green"
      }
    ]
}

Sample response

A successful response is indicated by an HTTP 200 OK response code, and includes the specified message in the response body, similar to the response from updating a message. The response does not include the newly created extended property.

Sample request

The second example creates one multi-value extended property for the specified message. That property is the only element in the MultiValueExtendedProperties array. The request body includes:

  • PropertyId which specifies the property as an array of strings with the specified GUID and the name Palette.
  • Value which specifies Palette as an array of 3 string values, ["Green", "Aqua", "Blue"].
PATCH https://outlook.office.com/api/v2.0/me/messages('AAMkAGE1M2_as77AACHsLrBBBA=')

Content-Type: application/json

{
  "MultiValueExtendedProperties": [
      {
         "PropertyId":"StringArray {66f5a359-4659-4830-9070-00049ec6ac6e} Name Palette",
         "Value":["Green", "Aqua", "Blue"]
      }
    ]
}

Sample response

A successful response is indicated by an HTTP 200 OK response code, and includes the specified message in the response body, similar to the response from updating a message. The response does not include the newly created extended property.

To see the newly created extended property, get the message expanded with the extended property.

Create extended property in a new item

Create one or more extended properties while creating a new instance of a supported resource, all in the same POST call. Include the extended property or properties in the body of the POST request.

POST https://outlook.office.com/api/v2.0/me/messages
POST https://outlook.office.com/api/v2.0/me/events
POST https://outlook.office.com/api/v2.0/me/contacts
POST https://outlook.office.com/api/v2.0/me/tasks
POST https://outlook.office.com/api/v2.0/me/mailfolders
POST https://outlook.office.com/api/v2.0/me/calendars
POST https://outlook.office.com/api/v2.0/me/contactfolders
POST https://outlook.office.com/api/v2.0/me/taskfolders

Minimum required scope

One of the following read/write scopes corresponding to the targeted resource:

Parameter Type Description
Body parameters
SingleValueExtendedProperties Collection (SingleValueLegacyExtendedProperty) An array of one or more single-valued extended properties.
PropertyId string For each property in the SingleValueExtendedProperties collection, specify this to identify the property. It must follow one of the supported formats for single-value extended properties. Required.
Value string For each property in the SingleValueExtendedProperties collection, specify the property value. Required.
MultiValueExtendedProperties Collection (MultiValueLegacyExtendedProperty) An array of one or more multi-valued extended properties.
PropertyId string For each property in the MultiValueExtendedProperties collection, specify this to identify the property. It must follow one of the supported formats for multi-value extended properties. Required.
Value Collection(string) For each property in the MultiValueExtendedProperties collection, specify the values for that property. Required.

Sample request

The first example creates a new event and a single-value extended property. Apart from the properties you'd normally include for a new event, the request body includes the SingleValueExtendedProperties array that contains one single-value extended property, and the following for the property:

  • PropertyId specifies the property type as string, the GUID, and the property named Fun.
  • Value specifies Food as the value of the Fun property.
POST https://outlook.office.com/api/v2.0/me/events

Content-Type: application/json

{
  "Subject": "Celebrate Thanksgiving",
  "Body": {
    "ContentType": "HTML",
    "Content": "Let's get together!"
  },
  "Start": {
      "DateTime": "2015-11-26T18:00:00",
      "TimeZone": "Pacific Standard Time"
  },
  "End": {
      "DateTime": "2015-11-26T23:00:00",
      "TimeZone": "Pacific Standard Time"
  },
  "Attendees": [
    {
      "EmailAddress": {
        "Address": "Terrie@contoso.com",
        "Name": "Terrie Barrera"
      },
      "Type": "Required"
    }
  ],
  "SingleValueExtendedProperties": [
     {
           "PropertyId":"String {66f5a359-4659-4830-9070-00040ec6ac6e} Name Fun",
           "Value":"Food"
     }
  ]
}

Sample response

A successful response is indicated by an HTTP 201 Created response code, and includes the new event in the response body, similar to the response from creating just an event. The response does not include any newly created extended properties.

To see the newly created extended property, get the item expanded with the extended property.

Sample request

The second example creates a multi-value extended property in a new event all in the same POST operation. Apart from the properties you'd normally include for a new event, the request body includes the MultiValueExtendedProperties array that contains one extended property.

The request body includes the following for that multi-value extended property:

  • PropertyId which specifies the property as an array of strings with the specified GUID and the name Recreation.
  • Value which specifies Recreation as an array of 3 string values, ["Food", "Hiking", "Swimming"].
POST https://outlook.office.com/api/v2.0/me/events

Content-Type: application/json

{
  "Subject": "Family reunion",
  "Body": {
    "ContentType": "HTML",
    "Content": "Let's get together this Thanksgiving!"
  },
  "Start": {
      "DateTime": "2015-11-26T09:00:00",
      "TimeZone": "Pacific Standard Time"
  },
  "End": {
      "DateTime": "2015-11-29T21:00:00",
      "TimeZone": "Pacific Standard Time"
  },
  "Attendees": [
    {
      "EmailAddress": {
        "Address": "Terrie@contoso.com",
        "Name": "Terrie Barrera"
      },
      "Type": "Required"
    },
    {
      "EmailAddress": {
        "Address": "Lauren@contoso.com",
        "Name": "Lauren Solis"
      },
      "Type": "Required"
    }
  ],
  "MultiValueExtendedProperties": [
     {
           "PropertyId":"StringArray {66f5a359-4659-4830-9070-00050ec6ac6e} Name Recreation",
           "Value": ["Food", "Hiking", "Swimming"]
     }
  ]
}

Sample response

A successful response is indicated by an HTTP 201 Created response code, and includes the new event in the response body, similar to the response from creating just an event. The response does not include any newly created extended properties.

To see the newly created extended property, get the item expanded with the extended property.

Get item expanded with extended property

Get an instance of a supported resource expanded with the extended property that is specified by a filter on the PropertyId.

The string {propertyId_value} that you specify in the filter for PropertyId must follow one of the supported PropertyId formats. Make sure you apply URL encoding to the space characters in the filter string.

Expand item with matching single-value extended properties

GET https://outlook.office.com/api/v2.0/me/messages('{message_id}')?$expand=SingleValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/v2.0/me/events('{event_id}')?$expand=SingleValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/v2.0/me/contacts('{contact_id}')?$expand=SingleValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/v2.0/me/tasks('{task_id}')?$expand=SingleValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/v2.0/me/mailfolders('{mailFolder_id}')?$expand=SingleValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/v2.0/me/calendars('{calendar_id}')?$expand=SingleValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/v2.0/me/contactfolders('{contactFolder_id}')?$expand=SingleValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/v2.0/me/taskfolders('{taskfolder_id}')?$expand=SingleValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

Expand item with matching multi-value extended properties

GET https://outlook.office.com/api/v2.0/me/messages('{message_id}')?$expand=MultiValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/v2.0/me/events('{event_id}')?$expand=MultiValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/v2.0/me/contacts('{contact_id}')?$expand=MultiValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/v2.0/me/tasks('{task_id}')?$expand=MultiValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/v2.0/me/mailfolders('{mailFolder_id}')?$expand=MultiValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/v2.0/me/calendars('{calendar_id}')?$expand=MultiValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/v2.0/me/contactfolders('{contactFolder_id}')?$expand=MultiValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/v2.0/me/taskfolders('{taskfolder_id}')?$expand=MultiValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

Minimum required scope

One of the following read scopes corresponding to the targeted resource:

Sample request

The first example gets and expands the specified message by including a single-value extended property. The filter returns the extended property that has its PropertyId matching the string String {66f5a359-4659-4830-9070-00047ec6ac6e} Name Color (with URL encoding removed here for ease of reading).

GET https://outlook.office.com/api/v2.0/me/messages('AAMkAGE1M2_bs88AACHsLqWAAA=')?$expand=SingleValueExtendedProperties($filter=PropertyId%20eq%20'String%20{66f5a359-4659-4830-9070-00047ec6ac6e}%20Name%20Color')

Sample response

A successful response is indicated by an HTTP 200 OK response code.

The response body includes all the properties of the specified message and extended property returned from the filter.

{
    "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Messages/$entity",
    "@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Messages('AAMkAGE1M2_bs88AACHsLqWAAA=')",
    "@odata.etag": "W/\"CQAAABYAAACY4MQpaFz9SbqUDe4+bs88AACbyS4H\"",
    "Id": "AAMkAGE1M2_bs88AACHsLqWAAA=",
    "CreatedDateTime": "2015-11-11T02:41:24Z",
    "LastModifiedDateTime": "2015-12-09T04:07:57Z",
    "ChangeKey": "CQAAABYAAACY4MQpaFz9SbqUDe4+bs88AACbyS4H",
    "Categories": [
    ],
    "ReceivedDateTime": "2015-11-11T02:41:24Z",
    "SentDateTime": "2015-11-11T02:41:24Z",
    "HasAttachments": false,
    "InternetMessageId": "<SN2SR0101MB002977E7C30F9CA9AA55961484130@SN2SR0101MB0029.contoso.com>",
    "Subject": "RE: Talk about emergency prep",
    "Body": {
        "ContentType": "HTML",
        "Content": "<html>\r\n<head>\r\n<meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\">\r\n<meta content=\"text/html; charset=iso-8859-1\">\r\n<style type=\"text/css\" style=\"\">\r\n<!--\r\np\r\n\t{margin-top:0;\r\n\tmargin-bottom:0}\r\n-->\r\n</style>\r\n</head>\r\n<body dir=\"ltr\">\r\n<hr tabindex=\"-1\" style=\"display:inline-block; width:98%\">\r\n<div id=\"divRplyFwdMsg\" dir=\"ltr\"><font face=\"Calibri, sans-serif\" color=\"#000000\" style=\"font-size:11pt\"><b>From:</b> Christine Irwin<br>\r\n<b>Sent:</b> Sunday, November 8, 2015 12:28:31 AM<br>\r\n<b>To:</b> Terrie Barrera<br>\r\n<b>Subject:</b> Talk about emergency prep<br>\r\n<b>When:</b> Sunday, November 8, 2015 7:00 PM-8:00 PM.<br>\r\n<b>Where:</b> The Commons</font>\r\n<div>&nbsp;</div>\r\n</div>\r\n<div>\r\n<div id=\"divtagdefaultwrapper\" style=\"font-size:12pt; color:#000000; background-color:#FFFFFF; font-family:Calibri,Arial,Helvetica,sans-serif\">\r\n<p>Please see the attached before you come to the meeting.<br>\r\n</p>\r\n</div>\r\n</div>\r\n</body>\r\n</html>\r\n"
    },
    "BodyPreview": "________________________________",
    "Importance": "Normal",
    "ParentFolderId": "AQMkAGE1M2jgxCloXP1JupQN7j5uzzwAAAIBDwAAAA==",
    "Sender": {
        "EmailAddress": {
            "Name": "Christine Irwin",
            "Address": "christine@contoso.com"
        }
    },
    "From": null,
    "ToRecipients": [
        {
            "EmailAddress": {
                "Name": "Christine Irwin",
                "Address": "christine@contoso.com"
            }
        }
    ],
    "CcRecipients": [
    ],
    "BccRecipients": [
    ],
    "ReplyTo": [
    ],
    "ConversationId": "AAQkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVlLTY0YjcxZWUzNTE1MAAQAHWT1sRiMChEmlQCIZUadoU=",
    "IsDeliveryReceiptRequested": false,
    "IsReadReceiptRequested": false,
    "IsRead": true,
    "IsDraft": true,
    "WebLink": "https://outlook.office.com/owa/?ItemID=AAMkAGE1M2%2Bbs88AACHsLqWAAA%3D&exvsurl=1&viewmodel=ReadMessageItem",
    "MentionedMe": null,
    "HashtagDetailsPreview": null,
    "LikesPreview": null,
    "Mentioned": [
    ],
    "InferenceClassification": "Focused",
    "UnsubscribeData": [
    ],
    "UnsubscribeEnabled": false,
    "SingleValueExtendedProperties@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Messages('AAMkAGE1M2_bs88AACHsLqWAAA%3D')/SingleValueExtendedProperties",
    "SingleValueExtendedProperties": [
        {
            "PropertyId": "String {66f5a359-4659-4830-9070-00047ec6ac6e} Name Color",
            "Value": "Green"
        }
    ]
}

Sample request

The second example gets and expands the specified event by including a multi-value extended property. The filter returns the extended property that has its PropertyId matching the string StringArray {66f5a359-4659-4830-9070-00050ec6ac6e} Name Recreation (with URL encoding removed here for ease of reading).

GET https://outlook.office.com/api/v2.0/me/events('AAMkAGE1M2_bs88AACbuFiiAAA=')?$expand=MultiValueExtendedProperties($filter=PropertyId%20eq%20'StringArray%20{66f5a359-4659-4830-9070-00050ec6ac6e}%20Name%20Recreation')

Sample response

A successful response is indicated by an HTTP 200 OK response code.

The response body includes all the properties of the specified event and extended property returned from the filter.

{
    "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Events/$entity",
    "@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Events('AAMkAGE1M2_bs88AACbuFiiAAA=')",
    "@odata.etag": "W/\"mODEKWhc/Um6lA3uPm7PPAAAm8k15A==\"",
    "Id": "AAMkAGE1M2_bs88AACbuFiiAAA=",
    "CreatedDateTime": "2015-12-09T05:18:05.9477979Z",
    "LastModifiedDateTime": "2015-12-09T05:18:06.197802Z",
    "ChangeKey": "mODEKWhc/Um6lA3uPm7PPAAAm8k15A==",
    "Categories": [
    ],
    "OriginalStartTimeZone": "Pacific Standard Time",
    "OriginalEndTimeZone": "Pacific Standard Time",
    "ResponseStatus": {
        "Response": "Organizer",
        "Time": "0001-01-01T00:00:00Z"
    },
    "iCalUId": "04000000828A332796D9",
    "ReminderMinutesBeforeStart": 15,
    "IsReminderOn": true,
    "HasAttachments": false,
    "Subject": "Family reunion",
    "Body": {
        "ContentType": "HTML",
        "Content": "<html>\r\n<head>\r\n<meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\">\r\n<meta content=\"text/html; charset=us-ascii\">\r\n</head>\r\n<body>\r\nLet's get together this Thanksgiving!\r\n</body>\r\n</html>\r\n"
    },
    "BodyPreview": "Let's get together this Thanksgiving!",
    "Importance": "Normal",
    "Sensitivity": "Normal",
    "Start": {
        "DateTime": "2015-11-26T17:00:00.0000000",
        "TimeZone": "UTC"
    },
    "End": {
        "DateTime": "2015-11-30T05:00:00.0000000",
        "TimeZone": "UTC"
    },
    "Location": {
        "DisplayName": ""
    },
    "IsAllDay": false,
    "IsCancelled": false,
    "IsOrganizer": true,
    "Recurrence": null,
    "ResponseRequested": true,
    "SeriesMasterId": null,
    "ShowAs": "Busy",
    "Type": "SingleInstance",
    "Attendees": [
        {
            "Status": {
                "Response": "None",
                "Time": "0001-01-01T00:00:00Z"
            },
            "Type": "Required",
            "EmailAddress": {
                "Name": "Terrie Barrera",
                "Address": "Terrie@contoso.com"
            }
        },
        {
            "Status": {
                "Response": "None",
                "Time": "0001-01-01T00:00:00Z"
            },
            "Type": "Required",
            "EmailAddress": {
                "Name": "Lauren Solis",
                "Address": "Lauren@contoso.com"
            }
        }
    ],
    "Organizer": {
        "EmailAddress": {
            "Name": "Christine Irwin",
            "Address": "christine@contoso.com"
        }
    },
    "WebLink": "https://outlook.office.com/owa/?ItemID=AAMkAGE1M2%2Bbs88AACbuFiiAAA%3D&exvsurl=1&viewmodel=ICalendarItemDetailsViewModelFactory",
    "MultiValueExtendedProperties@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Events('AAMkAGE1M2_bs88AACbuFiiAAA%3D')/MultiValueExtendedProperties",
    "MultiValueExtendedProperties": [
        {
            "PropertyId": "StringArray {66f5a359-4659-4830-9070-00050ec6ac6e} Name Recreation",
            "Value": [
                "Food",
                "Hiking",
                "Swimming"
            ]
        }
    ]
}

Get item by filtering on extended property

Get instances of a supported resource that have the extended property specified by a filter on PropertyId and Value. The filter is applied to all instances of the resource in the signed-in user's mailbox. This filtering supports only single-value but not multi-value extended properties.

The string {propertyId_value} that you specify in the filter for PropertyId must follow one of the supported PropertyId formats.

If {property_value} is not a string, make sure you explicitly cast ep/value to the appropriate Edm data type when comparing it with {property_value}. See sample requests for non-string-typed properties below for examples of such casts.

Make sure you apply URL encoding to the following characters in the filter string: colon, forward slash, and space.

GET https://outlook.office.com/api/v2.0/me/messages?$filter=SingleValueExtendedProperties/Any(ep: ep/PropertyId eq '{propertyId_value}' and ep/Value eq '{property_value}')

GET https://outlook.office.com/api/v2.0/me/events?$filter=SingleValueExtendedProperties/Any(ep: ep/PropertyId eq '{propertyId_value}' and ep/Value eq '{property_value}')

GET https://outlook.office.com/api/v2.0/me/contacts?$filter=SingleValueExtendedProperties/Any(ep: ep/PropertyId eq '{propertyId_value}' and ep/Value eq '{property_value}')

GET https://outlook.office.com/api/v2.0/me/tasks?$filter=SingleValueExtendedProperties/Any(ep: ep/PropertyId eq '{propertyId_value}' and ep/Value eq '{property_value}')

GET https://outlook.office.com/api/v2.0/me/mailfolders?$filter=SingleValueExtendedProperties/Any(ep: ep/PropertyId eq '{propertyId_value}' and ep/Value eq '{property_value}')

GET https://outlook.office.com/api/v2.0/me/calendars?$filter=SingleValueExtendedProperties/Any(ep: ep/PropertyId eq '{propertyId_value}' and ep/Value eq '{property_value}')

GET https://outlook.office.com/api/v2.0/me/contactfolders?$filter=SingleValueExtendedProperties/Any(ep: ep/PropertyId eq '{propertyId_value}' and ep/Value eq '{property_value}')

GET https://outlook.office.com/api/v2.0/me/taskfolders?$filter=SingleValueExtendedProperties/Any(ep: ep/PropertyId eq '{propertyId_value}' and ep/Value eq '{property_value}')

Minimum required scope

One of the following read scopes corresponding to the targeted resource:

Sample request

The first example gets messages that have the single-value extended property specified in the filter. The filter returns the extended property that has:

  • Its PropertyId matching the string String {66f5a359-4659-4830-9070-00047ec6ac6e} Name Color (with URL encoding removed here for ease of reading).
  • Its Value being Green.
GET https://outlook.office.com/api/v2.0/Me/Messages?$filter=SingleValueExtendedProperties%2FAny(ep%3A%20ep%2FPropertyId%20eq%20'String%20{66f5a359-4659-4830-9070-00047ec6ac6e}%20Name%20Color'%20and%20ep%2FValue%20eq%20'Green')

The next two examples show how to get messages that have non-string typed single-value extended properties. For ease of reading, they do not include the necessary URL encoding. The following example shows a filter that looks for the extended property that has:

  • Its PropertyId matching the string CLSID {00062008-0000-0000-C000-000000000046} Name ConnectorSenderGuid.
  • Its Value being the GUID b9cf8971-7d55-4b73-9ffa-a584611b600b. To compare the property value with a GUID, cast ep/Value to Edm.Guid.
GET https://outlook.office.com/api/beta/me/Messages?$filter=SingleValueExtendedProperties/any(ep:ep/PropertyId eq 'CLSID {00062008-0000-0000-C000-000000000046} Name ConnectorSenderGuid' and cast(ep/Value, Edm.Guid) eq (b9cf8971-7d55-4b73-9ffa-a584611b600b))

The third and final example shows a filter that looks for the extended property that has:

  • Its PropertyId matching the string Integer {66f5a359-4659-4830-9070-00047ec6ac6e} Name Pallete.
  • Its Value equal to the integer 12. To compare the property value with an integer, cast ep/Value to Edm.Int32.
GET https://outlook.office.com/api/beta/me/Messages?$filter=SingleValueExtendedProperties/any(ep:ep/PropertyId eq 'Integer {66f5a359-4659-4830-9070-00047ec6ac6e} Name Pallete' and cast(ep/Value, Edm.Int32) eq 12)

Sample response

A successful response is indicated by an HTTP 200 OK response code, and the response body includes all the properties of the messages that have the extended property matching the corresponding filter. The response body is similar to the response from getting a message collection. The response does not include the matching extended property.

Next steps

Whether you're ready to start building an app or just want to learn more, we've got you covered.

Or, learn more about using the Office 365 platform: