• Article

ResolveNames Operation

Topic Last Modified: 2008-09-04

The ResolveNames operation resolves ambiguous e-mail 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 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.

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="https://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 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="https://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>

ResolveNames Error Response

Description

The following example shows an error response to a ResolveNames request. The error is caused by trying to resolve a name that cannot be resolved.

Code

<?xml version="1.0" encoding="utf-8" ?>
<soap:Envelope xmlns:soap="https://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="Error">
          <m:MessageText>No results were found.</m:MessageText>
          <m:ResponseCode>ErrorNameResolutionNoResults</m:ResponseCode>
          <m:DescriptiveLinkKey>0</m:DescriptiveLinkKey>
        </m:ResolveNamesResponseMessage>
      </m:ResponseMessages>
    </ResolveNamesResponse>
  </soap:Body>
</soap:Envelope>

Error Response Elements

The following elements are used in the error response: