Route public folder hierarchy requests

All requests for public folder information that require knowledge of the public folder hierarchy, such as moving, updating, deleting, or finding public folders, need to be routed to the default public folder hierarchy mailbox for the given user. To route the requests to that mailbox, you need to set the X-AnchorMailbox and X-PublicFolderMailbox headers to specific values returned by the Autodiscover service.

Overview of public folders

Header What do I need? How do I get it?
X-AnchorMailbox
The PublicFolderInformation value from a GetUserSettings Autodiscover SOAP response, which becomes the value of the X-AnchorMailbox header.

TODO
1. Send a GetUserSetting request with the SMTP address for the user's mailbox.

2. Cache the value of the PublicFolderInformation element that the Autodiscover service returns. This can be a cached from an existing Autodiscover call in your code, or a new EWS Managed API GetUserSettings call or a GetUserSettings SOAP request.

3. Use the PublicFolderInformation element to populate the value of the X-AnchorMailbox header. The value of the PublicFolderInformation element is an SMTP address.
X-PublicFolderMailbox
The Server value from a POX Autodiscover response, which becomes the value of the X-PublicFolderMailbox header.

TODO
1. Call the POX Autodiscover service using the X-AnchorMailbox email address.

2. Use the Server element returned by the Autodiscover service to populate the value of the X-PublicFolderMailbox header. The value of the X-PublicFolderMailbox is an SMTP address where the username is a GUID.

After you have determined the header values, include them when you make public folder hierarchy requests.

The steps in this article are specific to public folder hierarchy requests. To determine whether your request is a public folder hierarchy or content request, see Routing public folder requests.

Determine the value of the X-AnchorMailbox header by using the EWS Managed API

To retrieve the PublicFolderInformation (POX) value by using the EWS Managed API, you can either cache the value of the PublicFolderInformation element that an existing call to the Autodiscover service returns, or make a new call.

If you're making a new call, you can Get user settings by using the EWS Managed APIGet user settings by using the EWS Managed API to your code, and then call the GetUserSettings sample method by using the following code, which retrieves only the value of the PublicFolderInformation element. Include the SMTP address of the mailbox user as an input parameter.

GetUserSettingsResponse userResponse = GetUserSettings(adservice, "sonyaf@contoso.com", 3, UserSettingName.PublicFolderInformation);
Console.WriteLine("X-AnchorMailbox value for public folder hierarchy requests: {0}", userResponse.Settings[UserSettingName.PublicFolderInformation]);

After running the code, the following information is displayed on the console:

X-AnchorMailbox for public folder hierarchy requests: SharedPublicFolder@contoso.com

Now that you have the PublicFolderInformation value, include it as the value for the X-AnchorMailbox header in all public folder hierarchy requests.

X-AnchorMailbox: SharedPublicFolder@contoso.com

Determine the value of the X-AnchorMailbox header using SOAP

The following code example shows how to retrieve the PublicFolderInformation value by using the GetUserSettings SOAP operation. The mailbox user is specified in the Mailbox element, and the RequestedSettings element limits the response to the PublicFolderInformation value.

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:a="http://schemas.microsoft.com/exchange/2010/Autodiscover"
               xmlns:wsa="http://www.w3.org/2005/08/addressing"
               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <a:RequestedServerVersion>Exchange2007_SP1</a:RequestedServerVersion>
    <wsa:Action>http://schemas.microsoft.com/exchange/2010/Autodiscover/Autodiscover/GetUserSettings</wsa:Action>
    <wsa:To>https://pod51042.outlook.com/autodiscover/autodiscover.svc</wsa:To>
  </soap:Header>
  <soap:Body>
    <a:GetUserSettingsRequestMessage xmlns:a="http://schemas.microsoft.com/exchange/2010/Autodiscover">
      <a:Request>
        <a:Users>
          <a:User>
            <a:Mailbox>sonyaf@contoso.com</a:Mailbox>
          </a:User>
        </a:Users>
        <a:RequestedSettings>
          <a:Setting>PublicFolderInformation</a:Setting>
        </a:RequestedSettings>
      </a:Request>
    </a:GetUserSettingsRequestMessage>
  </soap:Body>
</soap:Envelope>

The response includes the PublicFolderInformation value.

<UserSetting i:type="StringSetting">
    <Name>PublicFolderInformation</Name>
    <Value>SharedPublicFolder@contoso.com</Value>
</UserSetting>

Now that you have the PublicFolderInformation value, include it as the value for the X-AnchorMailbox header in all public folder hierarchy requests.

X-AnchorMailbox: SharedPublicFolder@contoso.com

Make an Autodiscover request to determine the X-PublicFolderInformation value

Make an Autodiscover request by using the PublicFolderInformation SMTP address, which is now being used as the X-AnchorMailbox value. Use the Exchange 2013: Get user settings with Autodiscover code sample to call the Autodiscover service because it streamlines the Autodiscover process for you. This code sample uses the command line arguments listed in the following table to call the POX Autodiscover service on the PublicFolderInformation SMTP address.

Command-line argument Description
emailAddress
The PublicFolderInformation SMTP address.
-skipSOAP
Use POX Autodiscover requests for this scenario.
-auth authEmailAddress
The mailbox user's email address, which is used for authentication. You will be prompted to enter the mailbox user's password when you run the sample.

For example, when SharedPublicFolder@contoso.com is the SMTP address of the PublicFolderInformation element, and sonyaf@contoso.com is the mailbox user, the command-line arguments should look like this.

SharedPublicFolder@contoso.com -skipSOAP -auth sonyaf@contoso.com

When you run the Exchange 2013: Get user settings with Autodiscover sample, the last Autodiscover response should be successful and include all the user settings associated with the mailbox GUID. The Server value associated with the EXCH ProtocolType element is the X-PublicFolderInformation header value.

<Autodiscover xmlns="http://schemas.microsoft.com/exchange/autodiscover/responseschema/2006">
  <Response xmlns="http://schemas.microsoft.com/exchange/autodiscover/outlook/responseschema/2006a">
    …
    <Account>
      <AccountType>email</AccountType>
      <Action>settings</Action>
      <Protocol>
        <Type>EXCH</Type>
        <Server>1ec2a236-ed93-4f88-b9c6-33e63fa4aa44@contoso.com</Server>

Alternatively, if you do not want to use the Exchange 2013: Get user settings with Autodiscover sample, you can get the Server value by generating a list of Autodiscover endpoints, and then sending the following POX Autodiscover request to each URL until you receive a successful response. SharedPublicFolder@contoso.com is the value of the X-PublicFolderMailbox header.

<?xml version="1.0" encoding="utf-8"?>
<Autodiscover xmlns="http://schemas.microsoft.com/exchange/autodiscover/outlook/requestschema/2006">
  <Request>
    <EMailAddress>SharedPublicFolder@contoso.com</EMailAddress>
    <AcceptableResponseSchema>http://schemas.microsoft.com/exchange/autodiscover/outlook/responseschema/2006a</AcceptableResponseSchema>
  </Request>
</Autodiscover>

For more information about the Autodiscover process, see Autodiscover for Exchange, Generate a list of Autodiscover endpoints, and Get user settings from Exchange by using Autodiscover.

Set the values of the X-AnchorMailbox and X-PublicFolderMailbox headers

Using the value of the PublicFolderInformation SMTP address acquired in Determine the value of the X-AnchorMailbox header by using the EWS Managed API or Determine the value of the X-AnchorMailbox header using SOAP and the Server value acquired in Make an Autodiscover request to determine the X-PublicFolderInformation value, set the values of X-AnchorMailbox and X-PublicFolderMailbox headers in your public folder content request.

For example, given a PublicFolderInformation SMTP address of SharedPublicFolder@contoso.com and a Server value of 1ec2a236-ed93-4f88-b9c6-33e63fa4aa44@contoso.com, include the following headers when making calls to the following methods or operations.

X-AnchorMailbox: SharedPublicFolder@contoso.com
X-PublicFolderMailbox: 1ec2a236-ed93-4f88-b9c6-33e63fa4aa44@contoso.com

Public folder calls that require the X-AnchorMailbox and X-PublicFolder headers

EWS Managed API methods EWS operations
Folder.FindFolders
Folder.Delete
Folder.Update
Folder.Move
CreateFolder
FindFolder
DeleteFolder
UpdateFolder
MoveFolder

To add these headers by using the EWS Managed API, use the HttpHeaders.Add method.

service.HttpHeaders.Add("X-AnchorMailbox", "SharedPublicFolder@contoso.com");service.HttpHeaders.Add("X-PublicFolderMailbox", "1ec2a236-ed93-4f88-b9c6-33e63fa4aa44@contoso.com");

For example, the following code shows a FindFolder request with the X-AnchorMailbox and X-PublicFolderMailbox header set to the values retrieved in the examples in this article.

POST https://outlook.office365.com/EWS/Exchange.asmx HTTP/1.1
Content-Type: text/xml; charset=utf-8
User-Agent: SoapSender1.0
X-AnchorMailbox: SharedPublicFolder@contoso.com
X-PublicFolderMailbox: 1ec2a236-ed93-4f88-b9c6-33e63fa4aa44@contoso.com
Host: outlook.office365.com
Content-Length: 1174
Expect: 100-continue
Connection: Keep-Alive
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages" xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <t:RequestServerVersion Version="Exchange2013_SP1" />
  </soap:Header>
  <soap:Body>
    <m:FindFolder Traversal="Shallow">
      <m:FolderShape>
        <t:BaseShape>AllProperties</t:BaseShape>
      </m:FolderShape>
      <m:IndexedPageFolderView MaxEntriesReturned="1" Offset="0" BasePoint="Beginning" />
      <m:Restriction>
        <t:IsEqualTo>
          <t:FieldURI FieldURI="folder:DisplayName" />
          <t:FieldURIOrConstant>
            <t:Constant Value="My Public Contacts" />
          </t:FieldURIOrConstant>
        </t:IsEqualTo>
      </m:Restriction>
      <m:ParentFolderIds>
        <t:FolderId Id="AQEuAAADy/LIWjRCp0GFb0W6aGPbwwEARg5aCLUc8k6wLfl1c0a/2AAAAwIAAAA=" ChangeKey="AQAAABYAAABGDloItRzyTrAt+XVzRr/YAABdo/XB" />
      </m:ParentFolderIds>
    </m:FindFolder>
  </soap:Body>
</soap:Envelope>

See also