Share via


Best Practices: Important and critical headers for EWS

It's important to set several headers in your code help assure calls will work and to provide information to be used in diagnosing issues. As an example, some calls wither won't work or may only work against some servers if you don't set the X-AnchorMailbox header. If there is a need to review your application's traffic on the Exchange side, the User-Agent, client-request-id and return-client-request-id headers are extremely important if not critical as they help identify specific calls from your code.

Set headers to identify calls from your application:

The User-Agent header should be set so that any call from your application can be identified on the Exchange Server. This will show in the IIS logs. This header should be set to a unique string representing your application – usually the application name and sometimes its name and version are used. This header should be set for all EWS applications.

    oExchangeService.UserAgent = "MyApplication";

Identify each call:

Set headers to track each call to and from the server. This is done by setting two headers. Setting this can make troubleshooting much easier and in some cases, is needed to identify calls on the Exchange side so that an issue can be resolved. So, add these to all EWS applications from the start. The tracing in your application should record the GUID set on ClientRequestId with the traffic of the call.

Set ClientRequestId to a new GUID. It will be turned into the "client-request-id" header in the request and will be picked-up in Exchange side tracing and diagnostics. A new GUID needs to be generated for every call so that it is unique.

oExchangeService.ClientRequestId = Guid.NewGuid().ToString(); // Set a new GUID.

Setting ReturnClientRequestId will tell Exchange to set the "return-client-request-id" header in the response with the ClientRequestId of the request.

oExchangeService.ReturnClientRequestId = true;

Set the X-AnchorMailbox header:

When using EWS Impersonation specify the anchor mailbox by setting the "X-AnchorMailbox" mailbox header. This header is required for streaming notifications and accessing public folders. However, while not documented as necessary for other calls, it should be set to help assure calls work when Impersonation and AutoDiscover are used. If you get a 500, 503, odd behavior or calls just don't work with using EWS Impersonation then set this header. If you encounter any issue where Impersonation is involved, then check to see if this header is set and if its not set then see if adding it will resolve your issue.

oExchangeService.HttpHeaders.Add("X-AnchorMailbox", "mytargetmailbox@contoso.com");

Note that you can remove a prior set header with a call to the Remove method:

oExchangeService.HttpHeaders.Remove("X-AnchorMailbox");

. . .

if (oExchangeService.HttpHeaders.ContainsKey("X-AnchorMailbox"))
{

oExchangeService.HttpHeaders.Remove("X-AnchorMailbox");

oExchangeService.HttpHeaders.Add("X-AnchorMailbox", "mytargetmailbox2@contoso.com");

}

Reference:

Best Practices – EWS Authentication and Access Issues
https://blogs.msdn.microsoft.com/webdav_101/2015/05/11/best-practices-ews-authentication-and-access-issues/
        

Headers for accessing public folders:

When accessing Public Folders, you should always set two headers – "X-AnchorMailbox" and "X-PublicFolderMailbox".

oExchangeService.HttpHeaders.Add("X-AnchorMailbox", "mypublicfolder@contoso.com" );

oExchangeService.HttpHeaders.Add("X-PublicFolderMailbox", "mypublicfolder@contoso.com");

Reference:

How to: Route public folder hierarchy requests
https://msdn.microsoft.com/en-us/library/office/dn818490(v=exchg.150).aspx

Send client latencies header:

Set this to sends latency info which is used by Microsoft to improve EWS and Exchange 365. This header is not critical; however, it does help the caretakers of Exchange Online improve its service.

oExchangeService.SendClientLatencies = true;

 

Reference:

Please refer to the following for details:

 

Instrumenting client requests for EWS and REST in Exchange
https://msdn.microsoft.com/en-us/library/office/dn720380(v=exchg.150).aspx