Get singleValueLegacyExtendedProperty

Namespace: microsoft.graph

You can get a single resource instance expanded with a specific extended property, or a collection of resource instances that include extended properties matching a filter.

Using the query parameter $expand allows you to get the specified resource instance expanded with a specific extended property. Use a $filter and eq operator on the id property to specify the extended property. This is currently the only way to get the singleValueLegacyExtendedProperty object that represents an extended property.

To get resource instances that have certain extended properties, use the $filter query parameter and apply an eq operator on the id property. In addition, for numeric extended properties, apply one of the following operators on the value property: eq, ne,ge, gt, le, or lt. For string-typed extended properties, apply a contains, startswith, eq, or ne operator on value.

The filter is applied to all instances of the resource in the signed-in user's mailbox.

Filtering the string name (Name) in the id of an extended property is case-sensitive. Filtering the value property of an extended property is case-insensitive.

The following user resources are supported:

• calendar
• contact
• contactFolder
• event
• mailFolder
• message

As well as the following group resources:

• group calendar
• group event
• group post

See Extended properties overview for more information about when to use open extensions or extended properties, and how to specify extended properties.

This API is available in the following national cloud deployments.

Global service	US Government L4	US Government L5 (DOD)	China operated by 21Vianet
✅	✅	✅	✅

Permissions

Depending on the resource you're getting the extended property from and the permission type (delegated or application) you request, the permission specified in the following table is the minimum required to call this API. To learn more, including how to choose permissions, see Permissions.

Supported resource	Delegated (work or school account)	Delegated (personal Microsoft account)	Application
calendar	Calendars.Read	Calendars.Read	Calendars.Read
contact	Contacts.Read	Contacts.Read	Contacts.Read
contactFolder	Contacts.Read	Contacts.Read	Contacts.Read
event	Calendars.Read	Calendars.Read	Calendars.Read
group calendar	Group.Read.All	Not supported	Not supported
group event	Group.Read.All	Not supported	Not supported
group post	Group.Read.All	Not supported	Group.Read.All
mailFolder	Mail.Read	Mail.Read	Mail.Read
message	Mail.Read	Mail.Read	Mail.Read

HTTP request

GET a resource instance expanded with an extended property that matches a filter

Get a resource instance expanded with the extended property which matches a filter on the id property. Make sure you apply URL encoding to the space characters in the filter string.

Get a message instance:

GET /me/messages/{id}?$expand=singleValueExtendedProperties($filter=id eq '{id_value}')
GET /users/{id|userPrincipalName}/messages/{id}?$expand=singleValueExtendedProperties($filter=id eq '{id_value}')
GET /me/mailFolders/{id}/messages/{id}?$expand=singleValueExtendedProperties($filter=id eq '{id_value}')

Get a mailFolder instance:

GET /me/mailFolders/{id}?$expand=singleValueExtendedProperties($filter=id eq '{id_value}')
GET /users/{id|userPrincipalName}/mailFolders/{id}?$expand=singleValueExtendedProperties($filter=id eq '{id_value}')

Get an event instance:

GET /me/events/{id}?$expand=singleValueExtendedProperties($filter=id eq '{id_value}')
GET /users/{id|userPrincipalName}/events/{id}?$expand=singleValueExtendedProperties($filter=id eq '{id_value}')

Get a calendar instance:

GET /me/calendars/{id}?$expand=singleValueExtendedProperties($filter=id eq '{id_value}')
GET /users/{id|userPrincipalName}/calendars/{id}?$expand=singleValueExtendedProperties($filter=id eq '{id_value}')

Get a contact instance:

GET /me/contacts/{id}?$expand=singleValueExtendedProperties($filter=id eq '{id_value}')
GET /users/{id|userPrincipalName}/contacts/{id}?$expand=singleValueExtendedProperties($filter=id eq '{id_value}')
GET /me/contactFolders/{id}/contacts/{id}?$expand=singleValueExtendedProperties($filter=id eq '{id_value}')
GET /users/{id|userPrincipalName}/contactFolders/{id}/contacts/{id}?$expand=singleValueExtendedProperties($filter=id eq '{id_value}')

Get a contactFolder instance:

GET /me/contactfolders/{id}?$expand=singleValueExtendedProperties($filter=id eq '{id_value}')
GET /users/{id|userPrincipalName}/contactFolders/{id}?$expand=singleValueExtendedProperties($filter=id eq '{id_value}')

Get a group event instance:

GET /groups/{id}/events/{id}?$expand=singleValueExtendedProperties($filter=id eq '{id_value}')

Get a group post instance:

GET /groups/{id}/threads/{id}/posts/{id}?$expand=singleValueExtendedProperties($filter=id eq '{id_value}')
GET /groups/{id}/conversations/{id}/threads/{id}/posts/{id}?$expand=singleValueExtendedProperties($filter=id eq '{id_value}')

GET resource instances that include numeric extended properties matching a filter

Get instances of a supported resource that have a numeric extended property matching a filter. The filter uses an eq operator on the id property, and one of the following operators on the value property: eq, ne,ge, gt, le, or lt. Make sure you apply URL encoding to the following characters in the filter string - colon, forward slash, and space.

The following syntax lines show a filter that uses an eq operator on the id, and another eq operator on the property value. You can substitute the eq operator on the value by any one of the other operators (ne,ge, gt, le, or lt) that apply to numeric values.

Get message instances:

GET /me/messages?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and ep/value eq '{property_value}')
GET /users/{id|userPrincipalName}/messages?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and ep/value eq '{property_value}')
GET /me/mailFolders/{id}/messages?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and ep/value eq '{property_value}')

Get mailFolder instances:

GET /me/mailFolders?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and ep/value eq '{property_value}')
GET /users/{id|userPrincipalName}/mailFolders?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and ep/value eq '{property_value}')

Get event instances:

GET /me/events?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and ep/value eq '{property_value}')
GET /users/{id|userPrincipalName}/events?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and ep/value eq '{property_value}')

Get calendar instances:

GET /me/calendars?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and ep/value eq '{property_value}')
GET /users/{id|userPrincipalName}/calendars?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and ep/value eq '{property_value}')

Get contact instances:

GET /me/contacts?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and ep/value eq '{property_value}')
GET /users/{id|userPrincipalName}/contacts?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and ep/value eq '{property_value}')
GET /me/contactFolders/{id}/contacts?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and ep/value eq '{property_value}')
GET /users/{id|userPrincipalName}/contactFolders/{id}/contacts?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and ep/value eq '{property_value}')

Get contactFolder instances:

GET /me/contactfolders?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and ep/value eq '{property_value}')
GET /users/{id|userPrincipalName}/contactFolders?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and ep/value eq '{property_value}')

Get group event instances:

GET /groups/{id}/events?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and ep/value eq '{property_value}')

Get group post instances:

GET /groups/{id}/threads/{id}/posts?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and ep/value eq '{property_value}')
GET /groups/{id}/conversations/{id}/threads/{id}/posts?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and ep/value eq '{property_value}')

GET resource instances with string-typed extended properties matching a filter

Get instances of the message or event resource that have a string-typed extended property matching a filter. The filter uses an eq operator on the id property, and one of the following operators on the value property: contains, startswith, eq, or ne. Make sure you apply URL encoding to the following characters in the filter string - colon, forward slash, and space.

Get message instances:

GET /me/messages?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and contains(ep/value, '{property_value}'))
GET /users/{id|userPrincipalName}/messages?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and contains(ep/value, '{property_value}'))
GET /me/mailFolders/{id}/messages?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and contains(ep/value, '{property_value}'))

GET /me/messages?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and startswith(ep/value, '{property_value}'))
GET /users/{id|userPrincipalName}/messages?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and startswith(ep/value, '{property_value}'))
GET /me/mailFolders/{id}/messages?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and startswith(ep/value, '{property_value}'))

GET /me/messages?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and ep/value eq '{property_value}')
GET /users/{id|userPrincipalName}/messages?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and ep/value eq '{property_value}')
GET /me/mailFolders/{id}/messages?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and ep/value eq '{property_value}')

GET /me/messages?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and ep/value ne '{property_value}')
GET /users/{id|userPrincipalName}/messages?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and ep/value ne '{property_value}')
GET /me/mailFolders/{id}/messages?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and ep/value ne '{property_value}')

Get event instances:

GET /me/events?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and contains(ep/value, '{property_value}'))
GET /users/{id|userPrincipalName}/events?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and contains(ep/value, '{property_value}'))

GET /me/events?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and startswith(ep/value, '{property_value}'))
GET /users/{id|userPrincipalName}/events?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and startswith(ep/value, '{property_value}'))

GET /me/events?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and ep/value eq '{property_value}')
GET /users/{id|userPrincipalName}/events?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and ep/value eq '{property_value}')

GET /me/events?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and ep/value ne '{property_value}')
GET /users/{id|userPrincipalName}/events?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and ep/value ne '{property_value}')

Get group event instances:

GET /groups/{id}/events?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and contains(ep/value, '{property_value}'))
GET /groups/{id}/events?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and startswith(ep/value, '{property_value}'))
GET /groups/{id}/events?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and ep/value eq '{property_value}')
GET /groups/{id}/events?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and ep/value ne '{property_value}')

Path parameters

Parameter	Type	Description
id_value	String	The ID of the extended property to match. It must follow one of the supported formats. See Outlook extended properties overview for more information. Required.
property_value	String	The value of the extended property to match. Required where listed in the HTTP request section above. 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 request 4 below for examples.

Request headers

Name	Description
Authorization	Bearer {token}. Required. Learn more about authentication and authorization.

Request body

Don't supply a request body for this method.

Response

If successful, this method returns a 200 OK response code.

GET resource instance expanded with a matching extended property

The response body includes an object representing the requested resource instance, expanded with the matching singleValueLegacyExtendedProperty object.

GET resource instances that contain an extended property matching a filter

The response body includes one or more objects representing the resource instances that contain a matching extended property. The response body does not include the extended property.

Example

Request 1

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 id matching the string String {66f5a359-4659-4830-9070-00047ec6ac6e} Name Color (with URL encoding removed here for ease of reading).

HTTP

GET https://graph.microsoft.com/v1.0/me/messages/AAMkAGE1M2_bs88AACHsLqWAAA=?$expand=singleValueExtendedProperties($filter=id%20eq%20'String%20{66f5a359-4659-4830-9070-00047ec6ac6e}%20Name%20Color')

C#

// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Me.Messages["{message-id}"].GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Expand = new string []{ "singleValueExtendedProperties($filter=id eq 'String {66f5a359-4659-4830-9070-00047ec6ac6e} Name Color')" };
});

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

CLI

mgc users messages get --user-id {user-id} --message-id {message-id} --expand singleValueExtendedProperties(\$filter=id eq 'String {66f5a359-4659-4830-9070-00047ec6ac6e} Name Color')

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Go

// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
	  //other-imports
)

requestParameters := &graphusers.MessagesItemRequestBuilderGetQueryParameters{
	Expand: [] string {"singleValueExtendedProperties($filter=id eq 'String {66f5a359-4659-4830-9070-00047ec6ac6e} Name Color')"},
}
configuration := &graphusers.MessagesItemRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
messages, err := graphClient.Me().Messages().ByMessageId("message-id").Get(context.Background(), configuration)

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Java

// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

Message result = graphClient.me().messages().byMessageId("{message-id}").get(requestConfiguration -> {
	requestConfiguration.queryParameters.expand = new String []{"singleValueExtendedProperties($filter=id eq 'String {66f5a359-4659-4830-9070-00047ec6ac6e} Name Color')"};
});

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

let message = await client.api('/me/messages/AAMkAGE1M2_bs88AACHsLqWAAA=')
	.expand('singleValueExtendedProperties($filter=id eq \'String {66f5a359-4659-4830-9070-00047ec6ac6e} Name Color\')')
	.get();

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

PHP

<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Users\Item\Messages\Item\MessageItemRequestBuilderGetRequestConfiguration;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestConfiguration = new MessageItemRequestBuilderGetRequestConfiguration();
$queryParameters = MessageItemRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->expand = ["singleValueExtendedProperties(\$filter=id eq 'String {66f5a359-4659-4830-9070-00047ec6ac6e} Name Color')"];
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->me()->messages()->byMessageId('message-id')->get($requestConfiguration)->wait();

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

PowerShell

Import-Module Microsoft.Graph.Mail

# A UPN can also be used as -UserId.
Get-MgUserMessage -UserId $userId -MessageId $messageId -ExpandProperty "singleValueExtendedProperties(`$filter=id eq 'String {66f5a359-4659-4830-9070-00047ec6ac6e} Name Color')" 

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Python

# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.users.item.messages.item.message_item_request_builder import MessageItemRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
query_params = MessageItemRequestBuilder.MessageItemRequestBuilderGetQueryParameters(
		expand = ["singleValueExtendedProperties($filter=id eq 'String {66f5a359-4659-4830-9070-00047ec6ac6e} Name Color')"],
)

request_configuration = RequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.me.messages.by_message_id('message-id').get(request_configuration = request_configuration)

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Response 1

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

Note: The message object shown here is truncated for brevity. All of the properties will be returned from an actual call.

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Me/messages/$entity",
    "@odata.id": "https://graph.microsoft.com/v1.0/users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/messages('AAMkAGE1M2_bs88AACHsLqWAAA=')",
    "@odata.etag": "W/\"CQAAABYAAACY4MQpaFz9SbqUDe4+bs88AACbyS4H\"",
    "id": "AAMkAGE1M2_bs88AACHsLqWAAA=",
    "subject": "RE: Talk about emergency prep",
    "sender": {
        "emailAddress": {
            "name": "Christine Irwin",
            "address": "christine@contoso.com"
        }
    },
    "from": null,
    "toRecipients": [
        {
            "emailAddress": {
                "name": "Christine Irwin",
                "address": "christine@contoso.com"
            }
        }
    ],
    "singleValueExtendedProperties": [
        {
            "id": "String {66f5a359-4659-4830-9070-00047ec6ac6e} Name Color",
            "value": "Green"
        }
    ]
}

Request 2

The second example gets messages that have the string-typed single-value extended property specified in the filter. The filter looks for the extended property that has:

• Its id equal to the string String {66f5a359-4659-4830-9070-00047ec6ac6e} Name Color (with URL encoding removed here for ease of reading).

• Its value equal to the string Green.

GET https://graph.microsoft.com/v1.0/me/messages?$filter=singleValueExtendedProperties%2FAny(ep%3A%20ep%2Fid%20eq%20'String%20{66f5a359-4659-4830-9070-00047ec6ac6e}%20Name%20Color'%20and%20ep%2Fvalue%20eq%20'Green')

Response 2

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 filter. The response body is similar to the response from getting a message collection. The response does not include the matching extended property.

Request 3

The third example gets messages that have the string-typed single-value extended property specified in the filter. The filter looks for the extended property that has:

• Its id equal to the string String {66f5a359-4659-4830-9070-00047ec6ac6e} Name Color (with URL encoding removed here for ease of reading).

• Its value containing the string green.

GET https://graph.microsoft.com/v1.0/Me/messages?$filter=singleValueExtendedProperties/any(ep:ep/Id eq 'String {66f5a359-4659-4830-9070-00047ec6ac6e} Name Color' and contains(ep/Value, 'green'))

Response 3

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 filter. For example, a message that has a single-value extended property with the id equal to the string String {66f5a359-4659-4830-9070-00047ec6ac6e} Name Color, and the value Light green, would match the filter and be included in the response.

The response body is similar to the response from getting a message collection. The response does not include the matching extended property.

Request 4

The next 2 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 id 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://graph.microsoft.com/v1.0/me/messages?$filter=singleValueExtendedProperties/any(ep:ep/id eq 'CLSID {00062008-0000-0000-C000-000000000046} Name ConnectorSenderGuid' and cast(ep/value, Edm.Guid) eq (b9cf8971-7d55-4b73-9ffa-a584611b600b))

The next example shows a filter that looks for the extended property that has:

• Its id 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://graph.microsoft.com/v1.0/me/messages?$filter=singleValueExtendedProperties/any(ep:ep/id eq 'Integer {66f5a359-4659-4830-9070-00047ec6ac6e} Name Pallete' and cast(ep/value, Edm.Int32) eq 12)

Response 4

For each of the preceding 2 examples, 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.