GetImItemList operation
Find information about the GetImItemList EWS operation.
Using the GetImItemList operation
The GetImItemList operation retrieves the list of instant messaging (IM) groups and IM contact personas in a mailbox. The GetImItemList operation does not take any arguments.
This operation was introduced in Exchange Server 2013.
GetImItemList operation SOAP headers
The GetImItemList operation can use the SOAP headers that are listed in the following table.
Header name | Element | Description |
---|---|---|
Impersonation |
ExchangeImpersonation |
Identifies the user whom the client application is impersonating. This header is applicable to a request. |
MailboxCulture |
MailboxCulture |
Identifies the culture, as defined in RFC 3066, "Tags for the Identification of Languages", to be used to access the mailbox. This header is applicable to a request. |
RequestVersion |
RequestServerVersion |
Identifies the schema version for the operation request. This header is applicable to a request. |
ServerVersion |
ServerVersionInfo |
Identifies the version of the server that responded to the request. This header is applicable to a response. |
GetImItemList operation request example: Request your IM items list
The following example of a GetImItemList operation request shows how to request the list of IM groups and IM contact personas in a mailbox. The GetImItemList element is the only element option in the SOAP body.
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types"
xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages">
<soap:Header>
<t:RequestServerVersion Version="Exchange2013" />
<t:MailboxCulture>en-US</t:MailboxCulture>
</soap:Header>
<soap:Body >
<m:GetImItemList/>
</soap:Body>
</soap:Envelope>
The request SOAP body contains the following element:
Successful GetImItemList operation response
The following example shows a successful response to a GetImItemList operation request. The response contains four IM groups. Three of the IM groups — Other Contacts, Tagged, and Favorites — are default groups in the Exchange store. The MyCustomGroup2 group is a custom user-created group. The Other Contacts and Tagged groups do not have members. The Favorites group has a single contact member. The MyCustomGroup2 has two member contacts. The item identifiers are provided so that subsequent GetItem requests can be performed to get more information about the IM contacts.
This example returns two personas. The first persona represents two contact items: Anthony Smith and Tony Smith. The combined contact information is returned in the Persona object. The second persona represents a single contact with the display name of Terence Adams.
Note
The Exchange store identifiers, item identifiers, source identifiers, folder identifiers, and persona identifiers have been shortened to preserve readability.
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Header>
<h:ServerVersionInfo MajorVersion="15"
MinorVersion="0"
MajorBuildNumber="349"
MinorBuildNumber="0"
Version="Exchange2013"
xmlns="http://schemas.microsoft.com/exchange/services/2006/types"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:h="http://schemas.microsoft.com/exchange/services/2006/types" />
</s:Header>
<s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<GetImItemListResponse ResponseClass="Success"
xmlns="http://schemas.microsoft.com/exchange/services/2006/messages">
<ResponseCode>NoError</ResponseCode>
<ImItemList>
<Groups xmlns="http://schemas.microsoft.com/exchange/services/2006/types">
<ImGroup>
<DisplayName>Other Contacts</DisplayName>
<GroupType>IPM.DistList.MOC.OtherContacts</GroupType>
<ExchangeStoreId Id="AAMkAGQ1MjJjMTBkLThQoTbWAAAAAAQUAAA="
ChangeKey="EgAAAA==" />
</ImGroup>
<ImGroup>
<DisplayName>Tagged</DisplayName>
<GroupType>IPM.DistList.MOC.Tagged</GroupType>
<ExchangeStoreId Id="AAMkAGQ1MjJAAQTAAA="
ChangeKey="EgAAAA==" />
</ImGroup>
<ImGroup>
<DisplayName>Favorites</DisplayName>
<GroupType>IPM.DistList.MOC.Favorites</GroupType>
<ExchangeStoreId Id="AAMkAGQ1MjJjMTAAAAAQSAAA="
ChangeKey="EgAAAA==" />
<MemberCorrelationKey>
<ItemId Id="AAMkAGQ1MjJtt/bhQoTbWAAAAAAvcAAA="
ChangeKey="EQAAAA==" />
</MemberCorrelationKey>
</ImGroup>
<ImGroup>
<DisplayName>MyCustomGroup2</DisplayName>
<GroupType>IPM.DistList.MOC.UserGroup</GroupType>
<ExchangeStoreId Id="AAMkAGQ1MjJjKAAA="
ChangeKey="EgAAAA==" />
<MemberCorrelationKey>
<ItemId Id="AAMkAGQ1Matt/bhQoTbWAAAAAAvcAAA="
ChangeKey="EQAAAA==" />
<ItemId Id="AAMkAGQ1MjJjMTBkTbWAAAAAAveAAA="
ChangeKey="EQAAAA==" />
</MemberCorrelationKey>
</ImGroup>
</Groups>
<Personas xmlns="http://schemas.microsoft.com/exchange/services/2006/types">
<Persona>
<PersonaId Id="AAQkAGQ1MjJjMTBkLTc4YkZmRkYQAQAFgxE1nBcqRGgYWWorM9/+s=" />
<PersonaType>Person</PersonaType>
<CreationTime>2012-01-12T22:14:36Z</CreationTime>
<DisplayName>Anthony Smith</DisplayName>
<DisplayNameFirstLast>Anthony Smith</DisplayNameFirstLast>
<DisplayNameLastFirst>Smith Anthony</DisplayNameLastFirst>
<FileAs>Smith, Anthony</FileAs>
<FileAsId>LastCommaFirst</FileAsId>
<GivenName>Anthony</GivenName>
<Surname>Smith</Surname>
<EmailAddress>
<Name>tsmith@contoso.com</Name>
<EmailAddress>tsmith@contoso.com</EmailAddress>
<RoutingType>SMTP</RoutingType>
</EmailAddress>
<EmailAddresses>
<EmailAddress>
<Name>tsmith@contoso.com</Name>
<EmailAddress>tsmith@contoso.com</EmailAddress>
<RoutingType>SMTP</RoutingType>
</EmailAddress>
</EmailAddresses>
<ImAddress>tsmith@contoso.com</ImAddress>
<RelevanceScore>2147483647</RelevanceScore>
<Attributions>
<Attribution>
<Id>0</Id>
<SourceId Id="AQMkAGQ1MjIAYzEwZC03OGNlLTQ5Bq239uFChNtYAAAIvDAAAAA=="
ChangeKey="EQAAABYAAABtF8oI7iVOQatt/bhQoTbWAAAAADB3" />
<DisplayName>Outlook</DisplayName>
<IsWritable>true</IsWritable>
<IsQuickContact>false</IsQuickContact>
<IsHidden>false</IsHidden>
<FolderId Id="AQMkAGQ1MjIAYzEMikE3AQBtF8oI7iVOQatt/bhQoTbWAAADEAAAAA=="
ChangeKey="AQAAAA==" />
</Attribution>
<Attribution>
<Id>1</Id>
<SourceId Id="AAMkAGQ1MjJjMTBkLTc4Y2UtNDA5Ny04/bhQoTbWAAAAAAveAAA="
ChangeKey="EQAAABYAAABtF8oI7iVOQatt/bhQoTbWAAAAAAym" />
<DisplayName>Outlook</DisplayName>
<IsWritable>true</IsWritable>
<IsQuickContact>true</IsQuickContact>
<IsHidden>false</IsHidden>
<FolderId Id="AAMkAGQ1MjJjMTBkLTc4Y2UtNDA5Qatt/bhQoTbWAAAAAAvZAAA="
ChangeKey="AQAAAA==" />
</Attribution>
</Attributions>
<DisplayNames>
<StringAttributedValue>
<Value>Anthony Smith</Value>
<Attributions>
<Attribution>0</Attribution>
</Attributions>
</StringAttributedValue>
<StringAttributedValue>
<Value>Tony Smith</Value>
<Attributions>
<Attribution>1</Attribution>
</Attributions>
</StringAttributedValue>
</DisplayNames>
<FileAses>
<StringAttributedValue>
<Value>Smith, Anthony</Value>
<Attributions>
<Attribution>0</Attribution>
</Attributions>
</StringAttributedValue>
</FileAses>
<FileAsIds>
<StringAttributedValue>
<Value>LastCommaFirst</Value>
<Attributions>
<Attribution>0</Attribution>
</Attributions>
</StringAttributedValue>
<StringAttributedValue>
<Value>None</Value>
<Attributions>
<Attribution>1</Attribution>
</Attributions>
</StringAttributedValue>
</FileAsIds>
<GivenNames>
<StringAttributedValue>
<Value>Anthony</Value>
<Attributions>
<Attribution>0</Attribution>
</Attributions>
</StringAttributedValue>
</GivenNames>
<Surnames>
<StringAttributedValue>
<Value>Smith</Value>
<Attributions>
<Attribution>0</Attribution>
</Attributions>
</StringAttributedValue>
</Surnames>
<HomePhones>
<PhoneNumberAttributedValue>
<Value>
<Number>4255550110</Number>
<Type>Home</Type>
</Value>
<Attributions>
<Attribution>0</Attribution>
</Attributions>
</PhoneNumberAttributedValue>
</HomePhones>
<MobilePhones>
<PhoneNumberAttributedValue>
<Value>
<Number>4255550120</Number>
<Type>Mobile</Type>
</Value>
<Attributions>
<Attribution>0</Attribution>
</Attributions>
</PhoneNumberAttributedValue>
</MobilePhones>
<Emails1>
<EmailAddressAttributedValue>
<Value>
<Name>tsmith@contoso.com</Name>
<EmailAddress>tsmith@contoso.com</EmailAddress>
<RoutingType>SMTP</RoutingType>
</Value>
<Attributions>
<Attribution>0</Attribution>
<Attribution>1</Attribution>
</Attributions>
</EmailAddressAttributedValue>
</Emails1>
<ImAddresses>
<StringAttributedValue>
<Value>tsmith@contoso.com</Value>
<Attributions>
<Attribution>1</Attribution>
</Attributions>
</StringAttributedValue>
</ImAddresses>
</Persona>
<Persona>
<PersonaId Id="AAQkAGQ1MjJjMTBkLkYQAQAJ3EkhEEXN5KufGbSYJanZk=" />
<PersonaType>Person</PersonaType>
<CreationTime>2012-01-05T23:06:58Z</CreationTime>
<DisplayName>Terence Adams</DisplayName>
<DisplayNameFirstLast>Terence Adams</DisplayNameFirstLast>
<DisplayNameLastFirst>Terence Adams</DisplayNameLastFirst>
<FileAsId>None</FileAsId>
<EmailAddress>
<Name>Terence Adams</Name>
<EmailAddress>tadams@contoso.com</EmailAddress>
<RoutingType>SMTP</RoutingType>
</EmailAddress>
<EmailAddresses>
<EmailAddress>
<Name>Terence Adams</Name>
<EmailAddress>tadams@contoso.com</EmailAddress>
<RoutingType>SMTP</RoutingType>
</EmailAddress>
</EmailAddresses>
<ImAddress>tadams@contoso.com</ImAddress>
<RelevanceScore>2147483647</RelevanceScore>
<Attributions>
<Attribution>
<Id>0</Id>
<SourceId Id="AAMkAGQ1MjVOQatt/bhQoTbWAAAA7iVOQatt/bhQoTbWAAAAAAvcAAA="
ChangeKey="EQAAABYAAABtF8oI7iVOQatt/bhQoTbWAAAAAAyg" />
<DisplayName>Outlook</DisplayName>
<IsWritable>true</IsWritable>
<IsQuickContact>true</IsQuickContact>
<IsHidden>false</IsHidden>
<FolderId Id="AAMkAGQ1MjJjMTBkLTc4Y2rBtF8oI7iVOQatt/bhQoTbWAAAAAAvZAAA="
ChangeKey="AQAAAA==" />
</Attribution>
</Attributions>
<DisplayNames>
<StringAttributedValue>
<Value>Terence Adams</Value>
<Attributions>
<Attribution>0</Attribution>
</Attributions>
</StringAttributedValue>
</DisplayNames>
<FileAsIds>
<StringAttributedValue>
<Value>None</Value>
<Attributions>
<Attribution>0</Attribution>
</Attributions>
</StringAttributedValue>
</FileAsIds>
<Emails1>
<EmailAddressAttributedValue>
<Value>
<Name>Terence Adams</Name>
<EmailAddress>tadams@contoso.com</EmailAddress>
<RoutingType>SMTP</RoutingType>
</Value>
<Attributions>
<Attribution>0</Attribution>
</Attributions>
</EmailAddressAttributedValue>
</Emails1>
<ImAddresses>
<StringAttributedValue>
<Value>tadams@contoso.com</Value>
<Attributions>
<Attribution>0</Attribution>
</Attributions>
</StringAttributedValue>
</ImAddresses>
</Persona>
</Personas>
</ImItemList>
</GetImItemListResponse>
</s:Body>
</s:Envelope>
The response SOAP body contains the following elements:
GetImItemList operation error response
The following example shows an error response to a GetImItemList operation request. This is a response to a request that contains an incorrect requested server version in the SOAP header. This error response is a SOAP fault and is not represented in the EWS schema.
<?xml version="1.0" encoding="utf-8"?>
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<s:Fault>
<faultcode xmlns:a="http://schemas.microsoft.com/exchange/services/2006/types">a:ErrorIncorrectSchemaVersion</faultcode>
<faultstring xml:lang="en-US">The request is valid but does not specify the correct server version in the RequestServerVersion SOAP header. Ensure that the RequestServerVersion SOAP header is set with the correct RequestServerVersionValue.</faultstring>
<detail>
<e:ResponseCode xmlns:e="http://schemas.microsoft.com/exchange/services/2006/errors">ErrorIncorrectSchemaVersion</e:ResponseCode>
<e:Message xmlns:e="http://schemas.microsoft.com/exchange/services/2006/errors">The request is valid but does not specify the correct server version in the RequestServerVersion SOAP header. Ensure that the RequestServerVersion SOAP header is set with the correct RequestServerVersionValue.</e:Message>
</detail>
</s:Fault>
</s:Body>
</s:Envelope>