Edit

Communicate with EWS by using the EWS Managed API

  • Article

Find information about how to use the EWS Managed API to communicate with EWS in Exchange.

Note

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
Load
Gets properties on an item, attachment, or user configuration object.
GetItem operation

GetAttachment operation

GetUserConfiguration operation
Bind
Populates a new item on the client with information from an existing item on the server.
GetItem operation
Save
Saves the copy of the client item on the server.
UpdateItem operation

UpdateFolder operation

CreateItem operation

CreateFolder operation
Update
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.
UpdateItem operation

UpdateFolder operation
Delete
Deletes an item on the server.

For items and folders, the Delete method uses the and the DeleteFolder operation.
DeleteItem operation

DeleteFolder operation
Copy
Creates a copy of the item or folders on the server.
CopyItem operation

CopyFolder operation
Move
Moves items or folders on the server.
MoveItem operation

MoveFolder operation

To use the EWS Managed API to communicate with EWS

  1. Instantiate the ExchangeService class.

     ExchangeService service = new ExchangeService();

    Note

    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);

  2. 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("user1@contoso.com", "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");

    Note

    If the UseDefaultCredentials property is set to true, the value of the Credentials property is ignored.

  3. 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("user1@contoso.com");

    Note

    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.

See also