Use Autodiscover to find connection points
Find out how to use the Autodiscover service to direct your client application to the correct Exchange server.
The Exchange Autodiscover service provides your client application with configuration settings for email accounts that are hosted on Exchange Online, Exchange Online as part of Office 365, or an Exchange server running a version of Exchange starting with Exchange 2013. The Autodiscover service is a web service that provides configuration settings. The Autodiscover service is a web service that provides Exchange server configuration information to your client application. Client applications use Autodiscover to determine the endpoint of the Autodiscover service for a specific mailbox. This article explains how to follow the responses from an Exchange server to find the correct endpoint.
For information about how to get email address configuration settings, see Get user settings from Exchange by using Autodiscover and Get domain settings from an Exchange server.
Note
The process for finding the correct endpoint is part of the request for user or domain settings. The Autodiscover service uses a series of redirect responses to send the client application to the correct endpoint for an email address.
You can use one of the following Exchange development technologies to access the Autodiscover service:
The Exchange Web Services (EWS) Managed API
EWS
If you are using EWS, you can use the following methods to retrieve user settings:
The SOAP-based Autodiscover service
The XML (POX) Autodiscover service
An autogenerated proxy generated from the SOAP or XML Autodiscover service
For more information about these methods, see Autodiscover for Exchange.
For more information about these Exchange development technologies, see Explore the EWS Managed API, EWS, and web services in Exchange.
The EWS Managed API provides an object-based interface for retrieving user settings. If your client application uses managed code, we recommend that you use the EWS Managed API. The EWS Managed API interface is better optimized for a simple object model than the typical autogenerated web service proxy.
If you are using EWS, we suggest that you use the SOAP Autodiscover service, because it supports a richer set of features than the POX Autodiscover service.
Prerequisites for finding an endpoint
Before you can create a client application that uses the Autodiscover service, you need to have access to the following:
Exchange Online or a server that is running a version of Exchange starting with Exchange 2007 SP1. If you are using the SOAP-based Autodiscover service, Exchange Online or a version of Exchange starting with Exchange 2010.
An Exchange server that is configured to accept connections from your client application. For information about how to configure your Exchange server, see Controlling client application access to EWS in Exchange.
An account that is authorized to use EWS. For information about how to configure an account, see Controlling client application access to EWS in Exchange.
Note
If you are using the EWS Managed API, you must provide a certificate validation callback in some circumstances. You may also need a certificate validation callback with some generated proxy libraries, such as those created by Visual Studio. For more information, see Validate a server certificate for the EWS Managed API.
Core concepts for finding an endpoint
Before you use Autodiscover to find an endpoint, you should be familiar with the concepts listed in the following table.
| Concept | Description |
|---|---|
| Autodiscover for Exchange |
Provides an overview of how the Autodiscover service works. |
If you are using the EWS Managed API, you use the Microsoft.Exchange.WebServices.Data.ExchangeService class in the Microsoft.Exchange.WebServices.Data namespace to manage your connection to EWS. To use the EWS Managed API code samples in this article, you need to reference the following namespaces in your code:
System.Net
Microsoft.Exchange.WebServices.Data.ExchangeService
Find the correct endpoint by using the EWS Managed API
If you are using the EWS Managed API, calls to the Autodiscover service are handled by the ExchangeService class. To determine the correct endpoint for an email account, you call the AutodiscoverUrl method on an [ExchangeService] object. The following code example shows how to set the EWS web service endpoint for an email address to the Exchange.asmx file on the correct Client Access server by using the EWS Managed API.
NetworkCredential credentials = new NetworkCredential(securelyStoredEmail, securelyStoredPassword);
ExchangeService service = new ExchangeService(ExchangeVersion.Exchange2013);
service.Credentials = credentials;
service.AutodiscoverUrl("User1@contoso.com");
Find the correct endpoint by using EWS
The SOAP Autodiscover service may use a series of requests and responses to direct your application to the correct endpoint for EWS. For information about the process for determining the correct endpoint for an email account, see Autodiscover for Exchange. The following XML examples show the series of requests and responses that you can expect when making a SOAP Autodiscover request to find the correct endpoint.
SOAP Autodiscover endpoint request
The following example shows an XML request that is sent to the Autodiscover service to find the correct endpoint.
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:a="https://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="https://schemas.xmlsoap.org/soap/envelope/">
<soap:Header>
<a:RequestedServerVersion>Exchange2013</a:RequestedServerVersion>
<wsa:Action>https://schemas.microsoft.com/exchange/2010/Autodiscover/Autodiscover/GetUserSettings</wsa:Action>
<wsa:To>https://mail.microsoft.com/autodiscover/autodiscover.svc</wsa:To>
</soap:Header>
<soap:Body>
<a:GetUserSettingsRequestMessage xmlns:a="https://schemas.microsoft.com/exchange/2010/Autodiscover">
<a:Request>
<a:Users>
<a:User>
<a:Mailbox>User1@Contoso.com</a:Mailbox>
</a:User>
</a:Users>
<a:RequestedSettings>
<a:Setting>InternalEwsUrl</a:Setting>
<a:Setting>ExternalEwsUrl</a:Setting>
</a:RequestedSettings>
</a:Request>
</a:GetUserSettingsRequestMessage>
</soap:Body>
</soap:Envelope>
SOAP Autodiscover redirection response
The Autodiscover service may respond with one of two redirection responses: an HTTP 302 redirect, or a SOAP redirection response. If the response from the Exchange server is an HTTP 302 redirect, the client application should validate that the redirection address is acceptable and then follow the redirection response.
Important
For criteria for validating a redirection response, see Autodiscover for Exchange.
If the Autodiscover service returns a redirection response, indicated by the ErrorCode element of the UserResponse element, your client application should use the RedirectTarget element to construct a new settings request that is sent to the server specified in the redirection response. The following example shows a redirection response from the server.
<s:Envelope xmlns:s="https://schemas.xmlsoap.org/soap/envelope/" xmlns:a="http://www.w3.org/2005/08/addressing">
<s:Header>
<a:Action s:mustUnderstand="1">https://schemas.microsoft.com/exchange/2010/
Autodiscover/Autodiscover/GetUserSettingsResponse</a:Action>
<h:ServerVersionInfo xmlns:h="https://schemas.microsoft.com/exchange/2010/Autodiscover"
xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<h:MajorVersion>15</h:MajorVersion>
<h:MinorVersion>0</h:MinorVersion>
<h:MajorBuildNumber>682</h:MajorBuildNumber>
<h:MinorBuildNumber>1</h:MinorBuildNumber>
<h:Version>Exchange2013</h:Version>
</h:ServerVersionInfo>
</s:Header>
<s:Body>
<GetUserSettingsResponseMessage xmlns="https://schemas.microsoft.com/exchange/2010/Autodiscover">
<Response xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<ErrorCode>NoError</ErrorCode>
<ErrorMessage />
<UserResponses>
<UserResponse>
<ErrorCode>RedirectAddress</ErrorCode>
<ErrorMessage>Redirection address.</ErrorMessage>
<RedirectTarget>User1@mail.Contoso.com</RedirectTarget>
<UserSettingErrors />
<UserSettings />
</UserResponse>
</UserResponses>
</Response>
</GetUserSettingsResponseMessage>
</s:Body>
</s:Envelope>
After a redirection, the client uses the redirection URL to prepare another request. The following code shows an example of the request that you create from the redirection response.
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:a="https://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="https://schemas.xmlsoap.org/soap/envelope/">
<soap:Header>
<a:RequestedServerVersion>Exchange2013</a:RequestedServerVersion>
<wsa:Action>https://schemas.microsoft.com/exchange/2010/
Autodiscover/Autodiscover/GetUserSettings</wsa:Action>
<wsa:To>https://autodiscover.exchange.microsoft.com/autodiscover/autodiscover.svc</wsa:To>
</soap:Header>
<soap:Body>
<a:GetUserSettingsRequestMessage xmlns:a="https://schemas.microsoft.com/exchange/2010/Autodiscover">
<a:Request>
<a:Users>
<a:User>
<a:Mailbox>User1@mail.Contoso.com</a:Mailbox>
</a:User>
</a:Users>
<a:RequestedSettings>
<a:Setting>InternalEwsUrl</a:Setting>
<a:Setting>ExternalEwsUrl</a:Setting>
</a:RequestedSettings>
</a:Request>
</a:GetUserSettingsRequestMessage>
</soap:Body>
</soap:Envelope>
When the client application has been directed to the correct endpoint for the Autodiscover service, the server will send a response with the ErrorCode element of the UserResponse element set to NoError and containing the requested user settings. Only the requested user settings, InternalEwsUrl and ExternalEwsUrl, are returned. The following example shows the response from the server.
<s:Envelope xmlns:s="https://schemas.xmlsoap.org/soap/envelope/"
xmlns:a="http://www.w3.org/2005/08/addressing">
<s:Header>
<a:Action s:mustUnderstand="1">https://schemas.microsoft.com/exchange/2010/
Autodiscover/Autodiscover/GetUserSettingsResponse</a:Action>
<h:ServerVersionInfo xmlns:h="https://schemas.microsoft.com/exchange/2010/Autodiscover"
xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<h:MajorVersion>15</h:MajorVersion>
<h:MinorVersion>0</h:MinorVersion>
<h:MajorBuildNumber>160</h:MajorBuildNumber>
<h:MinorBuildNumber>4</h:MinorBuildNumber>
<h:Version>Exchange2013</h:Version>
</h:ServerVersionInfo>
</s:Header>
<s:Body>
<GetUserSettingsResponseMessage xmlns="https://schemas.microsoft.com/exchange/2010/Autodiscover">
<Response xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<ErrorCode>NoError</ErrorCode>
<ErrorMessage />
<UserResponses>
<UserResponse>
<ErrorCode>NoError</ErrorCode>
<ErrorMessage>No error.</ErrorMessage>
<RedirectTarget i:nil="true" />
<UserSettingErrors />
<UserSettings>
<UserSetting i:type="StringSetting">
<Name>InternalEwsUrl</Name>
<Value>https://server.Contoso.com/ews/exchange.asmx</Value>
</UserSetting>
<UserSetting i:type="StringSetting">
<Name>ExternalEwsUrl</Name>
<Value>https://server.Contoso.com/ews/exchange.asmx</Value>
</UserSetting>
</UserSettings>
</UserResponse>
</UserResponses>
</Response>
</GetUserSettingsResponseMessage>
</s:Body>
</s:Envelope>
Next steps
Finding the endpoint by following the Autodiscover process returns the requested domain or user settings. For information about making a request for specific settings, see the following articles: