Friday, September 18, 2015

EWS Create Mailbox folder Powershell module for Exchange and Office365 Mailboxes

This is a rollup post for a couple of scripts I've posted in the past for creating folders using EWS in an Exchange OnPremise or Exchange online Cloud mailbox. It can do the following

  • Create a Folder in the Root of the Mailbox
Create-Folder -Mailboxname mailbox@domain.com -NewFolderName test
  • Create a Folder as a SubFolder of the Inbox
Create-Folder -Mailboxname mailbox@domain.com -NewFolderName test -ParentFolder '\Inbox'
  • Create a Folder as a SubFolder of the Inbox using EWS Impersonation
Create-Folder -Mailboxname mailbox@domain.com -NewFolderName test -ParentFolder '\Inbox' -useImpersonation
  • Create a new Contacts Folder as a SubFolder of the Mailboxes Contacts Folder
Create-Folder -Mailboxname mailbox@domain.com -NewFolderName test -ParentFolder '\Contacts' -FolderClass IPF.Contact

  • Create a new Calendar Folder as a SubFolder of the Mailboxes Calendar Folder
Create-Folder -Mailboxname mailbox@domain.com -NewFolderName test -ParentFolder '\Calendar' -FolderClass IPF.Appointment

    The script will also detect if a folder with that name currently exists before trying to create a new folder.

I've put this module up on my github repo here you can download a copy here

The code looks like

function Connect-Exchange{ 
    param( 
     [Parameter(Position=0, Mandatory=$true)] [string]$MailboxName,
 [Parameter(Position=1, Mandatory=$true)] [System.Management.Automation.PSCredential]$Credentials
    )  
  Begin
   {
  Load-EWSManagedAPI
  
  ## Set Exchange Version  
  $ExchangeVersion = [Microsoft.Exchange.WebServices.Data.ExchangeVersion]::Exchange2010_SP1
    
  ## Create Exchange Service Object  
  $service = New-Object Microsoft.Exchange.WebServices.Data.ExchangeService($ExchangeVersion)  
    
  ## Set Credentials to use two options are availible Option1 to use explict credentials or Option 2 use the Default (logged On) credentials  
    
  #Credentials Option 1 using UPN for the windows Account  
  #$psCred = Get-Credential  
  $creds = New-Object System.Net.NetworkCredential($Credentials.UserName.ToString(),$Credentials.GetNetworkCredential().password.ToString())  
  $service.Credentials = $creds      
  #Credentials Option 2  
  #service.UseDefaultCredentials = $true  
   #$service.TraceEnabled = $true
  ## Choose to ignore any SSL Warning issues caused by Self Signed Certificates  
    
  Handle-SSL 
    
  ## Set the URL of the CAS (Client Access Server) to use two options are availbe to use Autodiscover to find the CAS URL or Hardcode the CAS to use  
    
  #CAS URL Option 1 Autodiscover  
  $service.AutodiscoverUrl($MailboxName,{$true})  
  Write-host ("Using CAS Server : " + $Service.url)   
     
  #CAS URL Option 2 Hardcoded  
    
  #$uri=[system.URI] "https://casservername/ews/exchange.asmx"  
  #$service.Url = $uri    
    
  ## Optional section for Exchange Impersonation  
    
  #$service.ImpersonatedUserId = new-object Microsoft.Exchange.WebServices.Data.ImpersonatedUserId([Microsoft.Exchange.WebServices.Data.ConnectingIdType]::SmtpAddress, $MailboxName) 
  if(!$service.URL){
   throw "Error connecting to EWS"
  }
  else
  {  
   return $service
  }
 }
}

function Load-EWSManagedAPI{
    param( 
    )  
  Begin
 {
  ## Load Managed API dll  
  ###CHECK FOR EWS MANAGED API, IF PRESENT IMPORT THE HIGHEST VERSION EWS DLL, ELSE EXIT
  $EWSDLL = (($(Get-ItemProperty -ErrorAction SilentlyContinue -Path Registry::$(Get-ChildItem -ErrorAction SilentlyContinue -Path 'Registry::HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Exchange\Web Services'|Sort-Object Name -Descending| Select-Object -First 1 -ExpandProperty Name)).'Install Directory') + "Microsoft.Exchange.WebServices.dll")
  if (Test-Path $EWSDLL)
      {
      Import-Module $EWSDLL
      }
  else
      {
      "$(get-date -format yyyyMMddHHmmss):"
      "This script requires the EWS Managed API 1.2 or later."
      "Please download and install the current version of the EWS Managed API from"
      "http://go.microsoft.com/fwlink/?LinkId=255472"
      ""
      "Exiting Script."
      exit
      } 
   }
}

function Handle-SSL{
    param( 
    )  
  Begin
 {
  ## Code From http://poshcode.org/624
  ## Create a compilation environment
  $Provider=New-Object Microsoft.CSharp.CSharpCodeProvider
  $Compiler=$Provider.CreateCompiler()
  $Params=New-Object System.CodeDom.Compiler.CompilerParameters
  $Params.GenerateExecutable=$False
  $Params.GenerateInMemory=$True
  $Params.IncludeDebugInformation=$False
  $Params.ReferencedAssemblies.Add("System.DLL") | Out-Null

$TASource=@'
  namespace Local.ToolkitExtensions.Net.CertificatePolicy{
    public class TrustAll : System.Net.ICertificatePolicy {
      public TrustAll() { 
      }
      public bool CheckValidationResult(System.Net.ServicePoint sp,
        System.Security.Cryptography.X509Certificates.X509Certificate cert, 
        System.Net.WebRequest req, int problem) {
        return true;
      }
    }
  }
'@ 
  $TAResults=$Provider.CompileAssemblyFromSource($Params,$TASource)
  $TAAssembly=$TAResults.CompiledAssembly

  ## We now create an instance of the TrustAll and attach it to the ServicePointManager
  $TrustAll=$TAAssembly.CreateInstance("Local.ToolkitExtensions.Net.CertificatePolicy.TrustAll")
  [System.Net.ServicePointManager]::CertificatePolicy=$TrustAll

  ## end code from http://poshcode.org/624

 }
}

function Get-FolderFromPath{
 param (
         [Parameter(Position=0, Mandatory=$true)] [string]$FolderPath,
   [Parameter(Position=1, Mandatory=$true)] [string]$MailboxName,
   [Parameter(Position=2, Mandatory=$true)] [Microsoft.Exchange.WebServices.Data.ExchangeService]$service,
   [Parameter(Position=3, Mandatory=$false)] [Microsoft.Exchange.WebServices.Data.PropertySet]$PropertySet
    )
 process{
  ## Find and Bind to Folder based on Path  
  #Define the path to search should be seperated with \  
  #Bind to the MSGFolder Root  
  $folderid = new-object Microsoft.Exchange.WebServices.Data.FolderId([Microsoft.Exchange.WebServices.Data.WellKnownFolderName]::MsgFolderRoot,$MailboxName)   
  $tfTargetFolder = [Microsoft.Exchange.WebServices.Data.Folder]::Bind($service,$folderid)  
  #Split the Search path into an array  
  $fldArray = $FolderPath.Split("\") 
   #Loop through the Split Array and do a Search for each level of folder 
  for ($lint = 1; $lint -lt $fldArray.Length; $lint++) { 
         #Perform search based on the displayname of each folder level 
         $fvFolderView = new-object Microsoft.Exchange.WebServices.Data.FolderView(1) 
   if(![string]::IsNullOrEmpty($PropertySet)){
    $fvFolderView.PropertySet = $PropertySet
   }
         $SfSearchFilter = new-object Microsoft.Exchange.WebServices.Data.SearchFilter+IsEqualTo([Microsoft.Exchange.WebServices.Data.FolderSchema]::DisplayName,$fldArray[$lint]) 
         $findFolderResults = $service.FindFolders($tfTargetFolder.Id,$SfSearchFilter,$fvFolderView) 
         if ($findFolderResults.TotalCount -gt 0){ 
             foreach($folder in $findFolderResults.Folders){ 
                 $tfTargetFolder = $folder                
             } 
         } 
         else{ 
             Write-host ("Error Folder Not Found check path and try again")  
             $tfTargetFolder = $null  
             break  
         }     
     }  
  if($tfTargetFolder -ne $null){
   return [Microsoft.Exchange.WebServices.Data.Folder]$tfTargetFolder
  }
  else{
   throw ("Folder Not found")
  }
 }
}


####################### 
<# 
.SYNOPSIS 
 Creates a Folder in a Mailbox using the  Exchange Web Services API 
 
.DESCRIPTION 
  Creates a Folder in a Mailbox using the  Exchange Web Services API 
  
  Requires the EWS Managed API from https://www.microsoft.com/en-us/download/details.aspx?id=42951

.EXAMPLE
 Example 1 To create a Folder named test in the Root of the Mailbox
  Create-Folder -Mailboxname mailbox@domain.com -NewFolderName test
 
 Example 2 To create a Folder as a SubFolder of the Inbox
  Create-Folder -Mailboxname mailbox@domain.com -NewFolderName test -ParentFolder '\Inbox'
  
 Example 3 To create a new Folder Contacts SubFolder of the Contacts Folder
 Create-Folder -Mailboxname mailbox@domain.com -NewFolderName test -ParentFolder '\Contacts' -FolderClass IPF.Contact
 
 Example 4 To create a new Folder using EWS Impersonation 
  Create-Folder -Mailboxname mailbox@domain.com -NewFolderName test -ParentFolder '\Inbox' -useImpersonation

#> 
########################
function Create-Folder{
    param( 
      [Parameter(Position=0, Mandatory=$true)] [string]$MailboxName,
  [Parameter(Position=1, Mandatory=$true)] [System.Management.Automation.PSCredential]$Credentials,
  [Parameter(Position=2, Mandatory=$true)] [String]$NewFolderName,
  [Parameter(Position=3, Mandatory=$false)] [String]$ParentFolder,
  [Parameter(Position=4, Mandatory=$false)] [String]$FolderClass,
  [Parameter(Position=5, Mandatory=$false)] [switch]$useImpersonation
    )  
  Begin
  {
  $service = Connect-Exchange -MailboxName $MailboxName -Credentials $Credentials
  if($useImpersonation.IsPresent){
   $service.ImpersonatedUserId = new-object Microsoft.Exchange.WebServices.Data.ImpersonatedUserId([Microsoft.Exchange.WebServices.Data.ConnectingIdType]::SmtpAddress, $MailboxName)
  }
  $NewFolder = new-object Microsoft.Exchange.WebServices.Data.Folder($service)  
  $NewFolder.DisplayName = $NewFolderName 
  if(([string]::IsNullOrEmpty($folderClass))){
   $NewFolder.FolderClass = "IPF.Note"
  }
  else{
   $NewFolder.FolderClass = $folderClass
  }
  $EWSParentFolder = $null
  if(([string]::IsNullOrEmpty($ParentFolder))){
   # Bind to the MsgFolderRoot folder  
   $folderid= new-object Microsoft.Exchange.WebServices.Data.FolderId([Microsoft.Exchange.WebServices.Data.WellKnownFolderName]::MsgFolderRoot,$MailboxName)   
   $EWSParentFolder = [Microsoft.Exchange.WebServices.Data.Folder]::Bind($service,$folderid)
  }
  else{
   $EWSParentFolder =  Get-FolderFromPath -MailboxName $MailboxName -service $service -FolderPath $ParentFolder
  }
  #Define Folder Veiw Really only want to return one object  
  $fvFolderView = new-object Microsoft.Exchange.WebServices.Data.FolderView(1)  
  #Define a Search folder that is going to do a search based on the DisplayName of the folder  
  $SfSearchFilter = new-object Microsoft.Exchange.WebServices.Data.SearchFilter+IsEqualTo([Microsoft.Exchange.WebServices.Data.FolderSchema]::DisplayName,$NewFolderName)  
  #Do the Search  
  $findFolderResults = $service.FindFolders($EWSParentFolder.Id,$SfSearchFilter,$fvFolderView)  
  if ($findFolderResults.TotalCount -eq 0){  
      Write-host ("Folder Doesn't Exist")  
   $NewFolder.Save($EWSParentFolder.Id)  
   Write-host ("Folder Created")  
  }  
  else{  
      Write-error ("Folder already Exist with that Name")  
  }  
  
  
  }
}


3 comments:

Oliver Dresch said...

Hi Glen,
your script looks realy fantastic, but when I start your script in Powershell nothing happend. No error, no results.

Are there any Prerequisites to run the script? Exchange Version, Powershell etc.?

I´ve tryed your older script form there http://gsexdev.blogspot.com.au/2013/01/creating-new-calendarcontactstasks-or.html

That started and to the End I get an Error when script save "The Id property must be set."

I´ve you have any ideas I would appreciate your feedback.
Thanks
Oli

Glen Scales said...

the only prerequisite is that you need to have the EWS Managed API installed. to use the script you need to first load the Module eg

Import-Module ./Createfolder.pst -Force

Then you can run the cmdlets like

Create-Folder -Mailboxname mailbox@domain.com -NewFolderName test


Anonymous said...

Hi Glen,

is it possible to hand over the credentials from a earlier variable? What variable do I need to use?

Thank you