ResolveNames operation

Article
03/29/2023

The ResolveNames operation resolves ambiguous email addresses and display names.

Using the ResolveNames operation

This operation can be used to verify aliases and resolve display names to the appropriate mailbox user. If ambiguous names exist, the ResolveNames operation response provides information about each mailbox user so that the client application can resolve the names.

Remarks

The ResolveNames response returns a maximum of 100 candidates. The 100 candidates that are returned are the first 100 that are encountered in the lookup operation.

Email addresses with prefixed routing types, such as smtp or sip, are saved in a multivalue array. The ResolveNames operation performs a partial match against each value of that array when you add the routing type at the beginning of the unresolved name, such as "sip:User1@Contoso.com". If you don't specify a routing type, ResolveNames will default to the routing type of smtp, match it to a primary smtp address property, and not search the multivalue array.

Only one ambiguous name can be specified in a single request. Active Directory is searched first, and then the user's contact folder is searched. Resolved entries from a user's contact folder have a non-null ItemId property, which can then be used in a GetItem request. If it is the ID of a private distribution list, then it can be used in an ExpandDL operation. If the ReturnFullContactData attribute is set to true, then Active Directory entries found with the ResolveNames operation will return additional properties that describe a Contact. The ReturnFullContactData attribute does not affect the data that is returned for contacts and private distribution lists from the user's contact folder.

ResolveNames request example

Description

The following example of a ResolveNames request shows how to resolve the entry of User.

Code

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xmlns:xsd="http://www.w3.org/2001/XMLSchema"
               xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
               xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types">
  <soap:Body>
    <ResolveNames xmlns="https://schemas.microsoft.com/exchange/services/2006/messages"
                  xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types"
                  ReturnFullContactData="true">
      <UnresolvedEntry>User2</UnresolvedEntry>
    </ResolveNames>
  </soap:Body>
</soap:Envelope>

Comments

The response to this request will return all entries that start with "Jo" or "Mi." The returned items are public mailboxes, public and private distribution lists, and contacts.

Note

Only contacts in the default personal Contacts folder are searched.

The following are the possible results for a ResolveNames request:

Responses that do not contain a resolved entity will return a ResponseClass attribute value equal to Error. The MessageText element will contain " No results are found."
Responses that contain a single resolved entity will return a ResponseClass attribute value equal to Success.
Responses that contain multiple possible entities will return a ResponseClass attribute value equal to Warning. In this case, the entity could not be resolved to a unique identity. The MessageText element will contain "Multiple results are found."

Request elements

The following elements are used in the request:

Successful ResolveNames operation response example

Description

The following example shows a successful response to a ResolveNames request.

Code

<?xml version="1.0" encoding="utf-8" ?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" 
               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
               xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <soap:Header>
    <t:ServerVersionInfo MajorVersion="8" MinorVersion="0" MajorBuildNumber="685" MinorBuildNumber="8" 
                         xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types" />
  </soap:Header>
  <soap:Body>
    <ResolveNamesResponse xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages" 
                          xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types" 
                          xmlns="https://schemas.microsoft.com/exchange/services/2006/messages">
      <m:ResponseMessages>
        <m:ResolveNamesResponseMessage ResponseClass="Success">
          <m:ResponseCode>NoError</m:ResponseCode>
          <m:ResolutionSet TotalItemsInView="1" IncludesLastItemInRange="true">
            <t:Resolution>
              <t:Mailbox>
                <t:Name>User2</t:Name>
                <t:EmailAddress>User2@example.com</t:EmailAddress>
                <t:RoutingType>SMTP</t:RoutingType>
                <t:MailboxType>Mailbox</t:MailboxType>
              </t:Mailbox>
              <t:Contact>
                <t:DisplayName>User2</t:DisplayName>
                <t:EmailAddresses>
                  <t:Entry Key="EmailAddress1">SMTP:User2@example.com</t:Entry>
                </t:EmailAddresses>
                <t:ContactSource>ActiveDirectory</t:ContactSource>
              </t:Contact>
            </t:Resolution>
          </m:ResolutionSet>
        </m:ResolveNamesResponseMessage>
      </m:ResponseMessages>
    </ResolveNamesResponse>
  </soap:Body>
</soap:Envelope>

Successful ResolveNames response elements

The following elements are used in the response: