Exchange Web Services and PowerShell

Since Exchange 2007 SP1, the Exchange mail server includes Exchange Web Services (EWS), an interface for accessing items in the Exchange data store. For programming or scripting, the Exchange Web Services Managed API is available, which is a library that allows you to use EWS, even from PowerShell. This can be a useful tool, but the way to access user mailboxes seems peculiar. Even if you are an Exchange Admin, you do not have the permissions to retrieve information using EWS, and you must use Impersonation (described for Exchange 2007), which is, simply put, setting special permissions on user accounts.

This article is just a small guide on how to use EWS in PowerShell.

First, we need to load the EWS library.

Import-Module -Name "C:\Program Files\Microsoft\Exchange\Web Services\1.1\Microsoft.Exchange.WebServices.dll"

We create an Exchange service object, and it's important to specify the Exchange version (otherwise, we'll get an error when binding, and specifying SP2 didn't work for me).

$exchService = New-Object Microsoft.Exchange.WebServices.Data.ExchangeService([Microsoft.Exchange.WebServices.Data.ExchangeVersion]::Exchange2007_SP1)

We must specify the CAS server address, either manually or automatically using Autodiscover (for a specific user).

$exchService.Url = "https://mail.company.local/EWS/Exchange.asmx"
$exchService.AutodiscoverUrl("bouska@company.cz")

Another important step is to determine which mailbox we'll access and under which permissions. We have three options. In the first two, we specify the user we'll access, and by default, we access their mailbox. The first option uses the current user's credentials.

$exchService.UseDefaultCredentials = $true

Or we can specify the credentials of a specific user, and we must also provide their password.

$exchService.Credentials = New-Object Microsoft.Exchange.WebServices.Data.WebCredentials($user, "password", "domain")

The last option is to use impersonation, where we access the account specified in this function. By default, this is under the user who ran the script, and they must have Impersonation rights.

$exchService.ImpersonatedUserId = New-Object Microsoft.Exchange.WebServices.Data.ImpersonatedUserId([Microsoft.Exchange.WebServices.Data.ConnectingIdType]::SmtpAddress, "someone@company.cz")

Now we can connect to a user's folder (folder). In the example, we'll connect to the calendar.

$calendar = [Microsoft.Exchange.WebServices.Data.Folder]::Bind($exchService, [Microsoft.Exchange.WebServices.Data.WellKnownFolderName]::Calendar)

Here, we can, for example, display the permissions on the calendar. The second line displays information about the user assigned to the first item.

$calendar.Permissions
$calendar.Permissions[0].UserId

We can also set permissions (if permissions are already set for the given user, we'll get an error). At the end, we need to perform an update for the changes to take effect.

$FolderPermission = New-Object Microsoft.Exchange.WebServices.Data.FolderPermission("someone-else@company.cz", [Microsoft.Exchange.WebServices.Data.FolderPermissionLevel]::Reviewer)
$calendar.Permissions.Add($FolderPermission)
$calendar.Update()