Communicate with EWS by using the EWS Managed API
Find information about how to use the EWS Managed API to communicate with EWS in Exchange.
We’re removing the ability to use Basic authentication in Exchange Online for EWS beginning October 2022 Deprecation of Basic authentication in Exchange Online. You should use OAuth authentication instead. Authenticate an EWS application by using OAuth
The ExchangeService class in the EWS Managed API contains the methods and properties that you use to set user credentials, identify the EWS endpoint, send and receive SOAP messages, and configure the binding to communicate with EWS. Before you can use the EWS Managed API to perform any task, you have to create an instance of the ExchangeService class and bind it to EWS.
After you set up an ExchangeService object with user credentials and the EWS endpoint, any mailbox object that references the ExchangeService object can use the following method types to communicate with EWS:
- ExchangeService object methods — All the methods on the ExchangeService object that are not inherited from the base Object type make calls to EWS.
- Exchange mailbox item and folder type methods.
Table 1. Mailbox item and folder type methods that communicate with EWS
|Method||What it does||Operations that it calls|
||Gets properties on an item, attachment, or user configuration object.
||Populates a new item on the client with information from an existing item on the server.
||Saves the copy of the client item on the server.
||Updates the server with the changes made on the client.
For items and folders, the Update method uses the UpdateItem operation and the UpdateFolder operation.
||Deletes an item on the server.
For items and folders, the Delete method uses the and the DeleteFolder operation.
||Creates a copy of the item or folders on the server.
||Moves items or folders on the server.
To use the EWS Managed API to communicate with EWS
Instantiate the ExchangeService class.
ExchangeService service = new ExchangeService();
Instantiating ExchangeService with an empty constructor will create an instance that is bound to the latest known version of Exchange. Alternatively, you can target a specific version of Exchange by specifying version as a parameter.
ExchangeService service = new ExchangeService(ExchangeVersion.Exchange2007_SP1);
Set the credentials of the user who sends requests to the Exchange server. If you want to connect to EWS from a computer that is logged on to the domain, using the credentials of the authenticated user, set the UseDefaultCredentials property on the ExchangeService object to true.
// Connect by using the default credentials of the authenticated user. service.UseDefaultCredentials = true;
If you do not want to connect by using the default user credentials, set the Credentials property on the ExchangeService object to explicitly specify the credentials of a different user. If you are using Exchange Online or Exchange Online as part of Office 365, you'll use basic authentication, with just a user name and password. A domain name is required for NTLM authentication.
// Connect by using the credentials of user1 at contoso.com. service.Credentials = new WebCredentials("firstname.lastname@example.org", "password");
You can also specify the credentials of the user by using the user's domain name and password.
// Connect by using the credentials of contoso/user1. service.Credentials = new WebCredentials("user1", "password", "contoso");
If the UseDefaultCredentials property is set to true, the value of the Credentials property is ignored.
Set the URL of the EWS endpoint. This URL locates the exchange.asmx file on Client Access server.
// Use Autodiscover to set the URL endpoint. service.AutodiscoverUrl("email@example.com");
Although you can explicitly set the Url property of the ExchangeService to a hardcoded value, we recommend that you use the Autodiscover service instead, for the following reasons:
- Autodiscover determines the best endpoint for a given user (the endpoint that is closest to the user's Mailbox server).
- The EWS URL might change if new Client Access servers are deployed. In this scenario, using Autodiscover means no code changes are necessary.
- You should either set the URL explicitly or call AutodiscoverUrl, but you should not do both.