Rename Outlook attachments before you send them

Posted on May 21, 2015 by Scott — 9 Comments ↓

Edit (June 29,2017): I have made a couple minor changes to the code. One resolves the issue with to-be-renamed attachments being removed from the well when you don’t rename all attachments. The other may resolve the issue with the “path does not exist” error that some have gotten. I can’t be sure because I am unable to reproduce the error.

I often send PowerShell scripts via email. But because .ps1 is a Level 1 attachment, the recipient, if using Outlook, won’t be able to access it (by default). This means I need to rename the file before attaching it to the message. I don’t like doing that, however, because then I have to rename it back after attaching it. I can also compress (zip) the file or make a copy and rename that, but I still have extra files that I then have to delete. I would much rather deal with the file in the context I am sending it: Outlook.

I wrote a VBA macro several years ago that allows me to rename attachments after adding them to the message. Recently, I had an opportunity to share it with somebody so I took the time to update it to accommodate additional scenarios. For example, I discovered that when replying/forwarding a message that has inline images, those are included in the attachment collection, so I had to find a way to exclude those. The same is true when an embedded message is attached. Since the macro was being shared with others, I also added some additional error detection logic to deal with scenarios that normally wouldn’t apply to me or I could deal with one-off.

To use the macro, paste it into ThisOutlookSession in the VBA editor and save it. I modified the ribbon of the new message form (just using the built-in ribbon designer) to add a button that I labeled Rename Attachments and used one of the available icons (there aren’t a lot to choose from), clicking the button runs the macro. (You have to change the default macro security settings in the Trust Center because it isn’t digitally signed.)

Sub RenameAttachmentsWithPrompt()
    Dim olkItem As Outlook.MailItem
    Dim olkAttachment As Outlook.Attachment, olkAttachments As Outlook.Attachments
    Dim objFSO As Object, strFolder As String, strFilename As String
    Dim olkPA As PropertyAccessor
    Dim arrRenamedAttachments() As String
    Dim bValidAttachment, bRenamedAttachment As Boolean
    
    If Application.ActiveInspector Is Nothing Then
        Set olkItem = Application.ActiveExplorer.Selection.Item(1)
    Else
        Set olkItem = Application.ActiveInspector.CurrentItem
    End If
 
    i = 1
    bValidAttachment = False
    If olkItem.Attachments.Count > 0 Then
        If MsgBox("Do you want to rename any of the attachments?", vbYesNo, "Rename any attachments?") = vbYes Then
            Set olkAttachments = olkItem.Attachments
            Set objFSO = CreateObject("Scripting.FileSystemObject")
            'Bind to the system temp folder
            strFolder = objFSO.GetSpecialFolder(2)
            'Loop through attachments in reverse to account for
            'collection size changing when deleting an attachment
            For j = olkAttachments.Count To 1 Step -1
                Set olkAttachment = olkAttachments.Item(j)
                Set olkPA = olkAttachment.PropertyAccessor
                Dim bHidden As Boolean
                'Visible attachments usually don't have hidden property set so ignore error
                On Error Resume Next
                bHidden = olkPA.GetProperty("http://schemas.microsoft.com/mapi/proptag/0x7FFE000B")
                On Error GoTo 0
                'Skip embedded messages and hidden attachments
                If olkAttachment.Type <> olEmbeddeditem And (Not bHidden Or IsNull(bHidden)) Then
                    bValidAttachment = True
                    strFilename = ""
                    strFilename = InputBox("What do you want to name the attachment?" & _
                        vbNewLine & vbNewLine & "(To leave it as is, click OK or Cancel.)", _
                        "Rename Attachment", olkAttachment.FileName)
                    If strFilename <> olkAttachment.FileName And strFilename <> "" Then
                        'Attachment file names are read-only, so save renamed attachment to disk
                        'and delete original from message
                        ReDim Preserve arrRenamedAttachments(i - 1)
                        olkAttachment.SaveAsFile strFolder & "\" & strFilename
                        olkAttachment.Delete
                        arrRenamedAttachments(i - 1) = strFolder & "\" & strFilename
                        bRenamedAttachment = True
                        i = i + 1
                    End If
                End If
            Next
            If Not bValidAttachment Then
                noValid = MsgBox("There are no attachments that can be renamed." & vbNewLine & vbNewLine & _
                    "(Only embedded messages or hidden attachments are in the message.)", vbOKOnly)
            End If
            'Add renamed attachment(s) to message and delete from temp folder
            If bRenamedAttachment Then
                For Each strFilePath In arrRenamedAttachments
                    olkItem.Attachments.Add strFilePath
                    objFSO.DeleteFile strFilePath
                Next
            End If
        End If
    Else
        noAttach = MsgBox("There are no attachments in the message.", vbOKOnly)
    End If
    
    Set olkItem = Nothing
    Set olkAttachment = Nothing
    Set olkPA = Nothing
    Set objFSO = Nothing

End Sub

Sub RenameAttachmentsWithPrompt()

Dim olkItem As Outlook.MailItem

Dim olkAttachment As Outlook.Attachment, olkAttachments As Outlook.Attachments

Dim objFSO As Object, strFolder As String, strFilename As String

Dim olkPA As PropertyAccessor

Dim arrRenamedAttachments() As String

Dim bValidAttachment, bRenamedAttachment As Boolean

If Application.ActiveInspector Is Nothing Then

Set olkItem = Application.ActiveExplorer.Selection.Item(1)

Else

Set olkItem = Application.ActiveInspector.CurrentItem

End If

i = 1

bValidAttachment = False

If olkItem.Attachments.Count > 0 Then

If MsgBox("Do you want to rename any of the attachments?", vbYesNo, "Rename any attachments?") = vbYes Then

Set olkAttachments = olkItem.Attachments

Set objFSO = CreateObject("Scripting.FileSystemObject")

'Bind to the system temp folder

strFolder = objFSO.GetSpecialFolder(2)

'Loop through attachments in reverse to account for

'collection size changing when deleting an attachment

For j = olkAttachments.Count To 1 Step -1

Set olkAttachment = olkAttachments.Item(j)

Set olkPA = olkAttachment.PropertyAccessor

Dim bHidden As Boolean

'Visible attachments usually don't have hidden property set so ignore error

On Error Resume Next

bHidden = olkPA.GetProperty("http://schemas.microsoft.com/mapi/proptag/0x7FFE000B")

On Error GoTo 0

'Skip embedded messages and hidden attachments

If olkAttachment.Type <> olEmbeddeditem And (Not bHidden Or IsNull(bHidden)) Then

bValidAttachment = True

strFilename = ""

strFilename = InputBox("What do you want to name the attachment?" & _

vbNewLine & vbNewLine & "(To leave it as is, click OK or Cancel.)", _

"Rename Attachment", olkAttachment.FileName)

If strFilename <> olkAttachment.FileName And strFilename <> "" Then

'Attachment file names are read-only, so save renamed attachment to disk

'and delete original from message

ReDim Preserve arrRenamedAttachments(i - 1)

olkAttachment.SaveAsFile strFolder & "\" & strFilename

olkAttachment.Delete

arrRenamedAttachments(i - 1) = strFolder & "\" & strFilename

bRenamedAttachment = True

i = i + 1

End If

If Not bValidAttachment Then

noValid = MsgBox("There are no attachments that can be renamed." & vbNewLine & vbNewLine & _

"(Only embedded messages or hidden attachments are in the message.)", vbOKOnly)

End If

'Add renamed attachment(s) to message and delete from temp folder

If bRenamedAttachment Then

For Each strFilePath In arrRenamedAttachments

olkItem.Attachments.Add strFilePath

objFSO.DeleteFile strFilePath

End If

Else

noAttach = MsgBox("There are no attachments in the message.", vbOKOnly)

End If

Set olkItem = Nothing

Set olkAttachment = Nothing

Set olkPA = Nothing

Set objFSO = Nothing

End Sub

Script to set retention tag on default folder items updated to v1.1.1

Posted on April 2, 2015 by Scott — No Comments ↓

Articles in the "Retention tag on default folder items" series

Use EWS to apply retention policy to items in a default folder
Script to set retention tag on default folder items updated to v1.1.1 [This article]
Default folder retention tag script updated to 1.3
Updated script that applies retention tag to items in a default folder

When running v1.0 of the script in a folder with lots of items, it would keep stopping with no errors, but there were more items to process. I found that this was happening when the number of items to process changes because a new item was added to the folder. In other words, while processing deleted items and another item is added to the Deleted Items folder, the total number of items changes, resulting in Exchange not returning the next set of items correctly. v1.1 correctly accounts for this condition.

Additionally, I found that calendar items in the Deleted Items folder cannot be processed with the API. Trying to change any property returns an error that it can’t update calendar items that are already deleted. But since you can manually assign a tag to it in Outlook, I consider it a bug that you can’t update calendar items in the Deleted Items folder. So, I updated the search filter to exclude calendar items when not searching in the Calendar folder (processing meeting responses is okay; it is only appointment/meeting items that are affected).

You can now choose the default folder to process. If you don’t specify one, the Deleted Items folder is selected. I included all default folders that can have a retention policy tag assigned AND have a well-known folder ID. This means that you can’t use the script to process items in the Clutter or RSS Feeds folders. If you are interested in having the script work against those folders, let me know and I will add the code necessary to do so.

Download the updated version below. (The inline code of the first post has been updated, too.)

Set-DefaultFolderItemsTag.ps1 (9.4 KiB)

Previous in series | | Next in series

Use EWS to apply retention policy to items in a default folder

Posted on March 13, 2015 by Scott — No Comments ↓

Articles in the "Retention tag on default folder items" series

Use EWS to apply retention policy to items in a default folder [This article]
Script to set retention tag on default folder items updated to v1.1.1
Default folder retention tag script updated to 1.3
Updated script that applies retention tag to items in a default folder

When working with retention policies and the types of tags you can apply to folders and items, you can assign a personal tag to any item and to any custom folder. You cannot, however, assign a personal tag to a default folder (such as Deleted Items), even if a retention policy tag has not been assigned to the folder. This means that if no default policy tag has been assigned to the policy, the items in that folder will never expire. The only way for a user to expire items in that folder is to assign a personal tag to each and every item. For the deleted items folder, that can be a lot of items, and its contents are changing daily.

This script uses the EWS Managed API to get all items in the Deleted Items folder that do not have a tag assigned to them and then assign a specific tag to each. To start, you need to connect to EWS:

function Connect-WebServices ($smtpAddress)
	{
	$exchangeVersion = [Microsoft.Exchange.WebServices.Data.ExchangeVersion]::Exchange2013_SP1 
	$exchangeService = New-Object Microsoft.Exchange.WebServices.Data.ExchangeService($exchangeVersion) 
 	$exchangeService.Credentials = New-Object Microsoft.Exchange.WebServices.Data.WebCredentials($EXOCreds)
    #Use hard-coded URL
    $exchangeService.Url = 'https://outlook.office365.com/EWS/Exchange.asmx'
    #Impersonate mailbox
	#$exchangeService.ImpersonatedUserId = New-Object Microsoft.Exchange.WebServices.Data.ImpersonatedUserId([Microsoft.Exchange.WebServices.Data.ConnectingIdType]::SmtpAddress, $smtpAddress)
    $folderID= New-Object Microsoft.Exchange.WebServices.Data.FolderId([Microsoft.Exchange.WebServices.Data.WellKnownFolderName]::$DefaultFolder,$smtpAddress)     
    [Microsoft.Exchange.WebServices.Data.Folder]::Bind($exchangeService,$folderID)
	}

function Connect-WebServices ($smtpAddress)

{

$exchangeVersion = [Microsoft.Exchange.WebServices.Data.ExchangeVersion]::Exchange2013_SP1

$exchangeService = New-Object Microsoft.Exchange.WebServices.Data.ExchangeService($exchangeVersion)

$exchangeService.Credentials = New-Object Microsoft.Exchange.WebServices.Data.WebCredentials($EXOCreds)

#Use hard-coded URL

$exchangeService.Url = 'https://outlook.office365.com/EWS/Exchange.asmx'

#Impersonate mailbox

#$exchangeService.ImpersonatedUserId = New-Object Microsoft.Exchange.WebServices.Data.ImpersonatedUserId([Microsoft.Exchange.WebServices.Data.ConnectingIdType]::SmtpAddress, $smtpAddress)

$folderID= New-Object Microsoft.Exchange.WebServices.Data.FolderId([Microsoft.Exchange.WebServices.Data.WellKnownFolderName]::$DefaultFolder,$smtpAddress)

[Microsoft.Exchange.WebServices.Data.Folder]::Bind($exchangeService,$folderID)

}

I am using a function because I lifted this code from another one of my scripts, so calling this function returns an object for the Deleted Items folder. Based on the credentials format and EWS URL, you can see that I am connecting to Exchange Online. This can be easily changed to support on-premises. I am not using autodiscover because it is very slow when querying EXO, and since all EXO mailboxes can be accessed with the a single FQDN, it is simpler this way. I am not using impersonation because I am running this against my own mailbox, but you can uncomment the line if you choose to use it.

To search for items that do not have a tag assigned, this is used:

$policyTagProperty = New-Object Microsoft.Exchange.WebServices.Data.ExtendedPropertyDefinition(0x3019,[Microsoft.Exchange.WebServices.Data.MapiPropertyType]::Binary)
$itemView.PropertySet.Add($policyTagProperty)
$itemSearchFilter = New-Object Microsoft.Exchange.WebServices.Data.SearchFilter+Exists($policyTagProperty)
$itemSearchFilterNot = New-Object Microsoft.Exchange.WebServices.Data.SearchFilter+Not($itemSearchFilter)
$itemSearchResult = $folder.FindItems($itemSearchFilterNot,$itemView)

$policyTagProperty = New-Object Microsoft.Exchange.WebServices.Data.ExtendedPropertyDefinition(0x3019,[Microsoft.Exchange.WebServices.Data.MapiPropertyType]::Binary)

$itemView.PropertySet.Add($policyTagProperty)

$itemSearchFilter = New-Object Microsoft.Exchange.WebServices.Data.SearchFilter+Exists($policyTagProperty)

$itemSearchFilterNot = New-Object Microsoft.Exchange.WebServices.Data.SearchFilter+Not($itemSearchFilter)

$itemSearchResult = $folder.FindItems($itemSearchFilterNot,$itemView)

The MAPI property that indicates whether a tag has been assigned (whether implicitly or explicitly) is an extended property that you declare and add to a property set. The property is binary and contains the GUID of the tag, but since I am only looking for items without a tag, I only care if the property has a value. To do this, you first define a search filter object that says to include items where the property exists. Then to negate that, so I can find items without that property, you create another search filter object using the Not class that contains the other search filter.

Then you can apply the tag and its corresponding days until expiration value:

$policyTagGUID = New-Object Guid("{33CEDA03-0536-424C-8ECA-E839E0BC5945}")
$item.SetExtendedProperty($policyTagProperty, $policyTagGUID.ToByteArray())
$retentionPeriodProperty = New-Object Microsoft.Exchange.WebServices.Data.ExtendedPropertyDefinition(0x301A,[Microsoft.Exchange.WebServices.Data.MapiPropertyType]::Integer)
$item.SetExtendedProperty($retentionPeriodProperty, 30)
$item.Update([Microsoft.Exchange.WebServices.Data.ConflictResolutionMode]::AlwaysOverwrite,[Microsoft.Exchange.WebServices.Data.SendInvitationsOrCancellationsMode]::SendToNone)

$policyTagGUID = New-Object Guid("{33CEDA03-0536-424C-8ECA-E839E0BC5945}")

$item.SetExtendedProperty($policyTagProperty, $policyTagGUID.ToByteArray())

$retentionPeriodProperty = New-Object Microsoft.Exchange.WebServices.Data.ExtendedPropertyDefinition(0x301A,[Microsoft.Exchange.WebServices.Data.MapiPropertyType]::Integer)

$item.SetExtendedProperty($retentionPeriodProperty, 30)

$item.Update([Microsoft.Exchange.WebServices.Data.ConflictResolutionMode]::AlwaysOverwrite,[Microsoft.Exchange.WebServices.Data.SendInvitationsOrCancellationsMode]::SendToNone)

To assign the tag, you need to know its GUID. You can get this from PowerShell, but if you don’t have access to Exchange to get this, you can manually assign the tag to an item, then use MFCMAPI and look at the item’s properties for the value in PR_POLICY_TAG (0x30190102). The RAW representation of the GUID will need to be converted to the proper byte order, which can be done in a variety of ways, but this site is an easy way. When assigning the tag you also have to set the property that contains the number of days after which the tag is configured to expire. In my case, it is a 30-day tag. (I tested not setting the property and the result in Outlook does show that the tag is assigned but it doesn’t show the expiration date. I don’t know if the property is only used to calculate the displayed date or if MRM actually uses it when expiring items.)

The complete script can be downloaded from the link or copied from the code below. It includes checking for the EWS Managed API and a progress bar (since this is not a fast operation).

Set-DefaultFolderItemsTag.ps1 (9.4 KiB)

#Apply retention tag to items in deleted items folder that do not have one
#1.6.1 Added policy GUID back to EXO mailboxes (issue resolved in service)
#1.6 Updated for changes in EXO, change loop to get all items and then update all items,
#	 added parameters for target environment and impersonation
#1.5 Added option of updating items that already have a tag
#1.4 Added choice of tag to apply
#1.3 Fixed processing of calendar items
#1.2 Update calendar items that can be, note the count that cannot be
#1.1.2 Prefill cred username with email address of target mailbox

<#
	.Synopsis
		Assign personal tag to all items in a default folder.
	.Description
		Get all items in a folder that do not have a retention tag explicitly
        assigned and assign a personal tag them.
	.Parameter EmailAddress
		Email address of mailbox to process
	.Parameter DefaultFolder
		The name of the default folder to process.  Default value is DeletedItems.
	.Parameter DaysToRetain
		Number of days to retain an item for.  Must match one of the defined
		personal tags in the Variables region.
	.Parameter OverwriteExistingTags
		Switch to indicate that items with a tag that does not match the tag to be assigned
		are updated.  The default is to update only items that do not have a tag.
	.Parameter Environment
		Specify whether the target environment is Exchange Online or Exchange on-premises.
		The default is Exchange Online.
	.Parameter UseImpersonation
		Switch to indicate impersonation should be used instead of full or delegate access.
	.Example
		Set-DefaultFolderItemsTag.ps1 user@domain
	.Example
		Set-DefaultFolderItemsTag.ps1 user@domain -DefaultFolder SentItems -DaysToRetain 365
	.Notes
		Version: 1.6.1
		Date: 12/1/17
	#>

Param (
	[Parameter(Position=0,Mandatory=$true,HelpMessage="Email address of mailbox")][string]$EmailAddress,
    [Parameter(Position=1,Mandatory=$false,HelpMessage="Name of default folder to process")]
    [ValidateSet('Calendar','ConversationHistory','DeletedItems','Inbox','Journal','JunkEmail','Notes','SentItems','SyncIssues','Tasks')]
    	[string]$DefaultFolder = 'DeletedItems',
	[Parameter(Position=2,Mandatory=$true)][ValidateSet(30,365)][int]$DaysToRetain,
	[ValidateSet('Online','OnPremises')]$Environment = 'Online',
	[switch]$UseImpersonation,
	[switch]$OverwriteExistingTags
	)

#Region Variables

#Replace with GUIDs of tag to assign to items and the number of days each tag retains items
$30DayTag = '{33CEDA03-0536-424C-8ECA-E839E0BC5945}',30
$365DayTag = '{AE331EBC-934F-43E2-8AB9-8480CE98E457}',365

#EndRegion
switch ($DaysToRetain)
	{
	30
		{
		$personalTagGUID = $30DayTag[0]
		$personalTagRetentionDays = $30DayTag[1]
		}
	365
		{
		$personalTagGUID = $365DayTag[0]
		$personalTagRetentionDays = $365DayTag[1]
		}
	}
		

#Check for EWS API
$apiPath = (($(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 $apiPath)
	{
	Add-Type -Path $apiPath
	}
else
	{
	Write-Error "The Exchange Web Services Managed API is required to use this script." -Category NotInstalled
	break
	}

function Connect-WebServices ($smtpAddress, $folder)
	{
	$exchangeVersion = [Microsoft.Exchange.WebServices.Data.ExchangeVersion]::Exchange2013_SP1 
	$exchangeService = New-Object -TypeName Microsoft.Exchange.WebServices.Data.ExchangeService($exchangeVersion) 
 	$exchangeService.Credentials = New-Object -TypeName Microsoft.Exchange.WebServices.Data.WebCredentials($EXOCreds)
    #Use hard-coded URL
    $exchangeService.Url = 'https://outlook.office365.com/EWS/Exchange.asmx'
    #Enable tracing to debug
    #$exchangeService.TraceEnabled = $true
    if ($UseImpersonation)
		{
		$exchangeService.ImpersonatedUserId = New-Object -TypeName Microsoft.Exchange.WebServices.Data.ImpersonatedUserId([Microsoft.Exchange.WebServices.Data.ConnectingIdType]::SmtpAddress, $smtpAddress)
		}
    $folderID = New-Object -TypeName Microsoft.Exchange.WebServices.Data.FolderId([Microsoft.Exchange.WebServices.Data.WellKnownFolderName]::$folder,$smtpAddress)     
    [Microsoft.Exchange.WebServices.Data.Folder]::Bind($exchangeService,$folderID)
	}

function Apply-RetentionTag
    {
    #Bind to folder of mailbox
    $folder = Connect-WebServices -smtpAddress $EmailAddress -folder $DefaultFolder
    if (-not($folder))
        {
        Write-Error -Message "Error binding to folder in mailbox for $EmailAddress." -Category ConnectionError
        }
    else
        {
		$pageSize = 50
		$offset = 0
		$moreItems = $true
		$items = $null
		$firstRun = $true
        while ($moreItems)
            {
            if ($firstRun)
				{
				$percentComplete = -1
				}
			else
				{
				$percentComplete = $items.Count/$totalItems*100
				Write-Verbose -Message "$($items.Count) of $totalItems have been retrieved."
				}
			if ($OverwriteExistingTags)
				{
				Write-Progress -Activity "Apply retention tag to $DefaultFolder" -CurrentOperation "Retrieving all items in folder" -PercentComplete $percentComplete -Status ' '
				}
			else
				{
				Write-Progress -Activity "Apply retention tag to $DefaultFolder" -CurrentOperation "Retrieving items with no tag" -PercentComplete $percentComplete -Status ' '
				}
			#Set up paged search to stay below FindCountLimit
            $itemView = New-Object -TypeName Microsoft.Exchange.WebServices.Data.ItemView($pageSize,$offset,[Microsoft.Exchange.WebServices.Data.OffsetBasePoint]::Beginning)
            $itemView.Traversal = [Microsoft.Exchange.WebServices.Data.ItemTraversal]::Shallow
            $itemView.PropertySet = New-Object -TypeName Microsoft.Exchange.WebServices.Data.PropertySet([Microsoft.Exchange.WebServices.Data.BasePropertySet]::IdOnly)
			$itemView.PropertySet.Add([Microsoft.Exchange.WebServices.Data.ItemSchema]::DateTimeCreated)
			#Property that contains the number of days for the applied tag
			$retentionPeriodProperty = New-Object -TypeName Microsoft.Exchange.WebServices.Data.ExtendedPropertyDefinition(0x301A,[Microsoft.Exchange.WebServices.Data.MapiPropertyType]::Integer)
            $itemView.PropertySet.Add($retentionPeriodProperty)
			if ($OverwriteExistingTags) #Get all items, regardless of whether tag is applied
				{
				$itemSearchResult = $folder.FindItems($itemView)
				}
			else
				{
				#Create the search filter to find items with no retention period applied
				$itemSearchFilter = New-Object -TypeName Microsoft.Exchange.WebServices.Data.SearchFilter+Exists($retentionPeriodProperty)
				$itemSearchFilterNot = New-Object -TypeName Microsoft.Exchange.WebServices.Data.SearchFilter+Not($itemSearchFilter)
	            $itemSearchResult = $folder.FindItems($itemSearchFilterNot,$itemView)
				}
            
            if ($firstRun)
                {
                if ($itemSearchResult.TotalCount -eq 0)
                    {
                    Write-Host "There are no items to process in $($DefaultFolder)."
					exit
                    }
                else
                    {
                    Write-Verbose -Message "Initial search results total item count: $($itemSearchResult.TotalCount)"
					$totalItems = $itemSearchResult.TotalCount
                    $firstRun = $false
                    }
                }
        	
			$items += $itemSearchResult.Items
			
			if ($itemSearchResult.MoreAvailable -eq $false)
                {
				$moreItems = $false
				Write-Verbose -Message "More items is set to False."
				}
            if ($moreItems)
                {
				$offset += $pageSize
				Write-Verbose -Message "Offset is $offset."
				}
            }
			
            #Process each item in search result collection
			$itemCount = 0
            foreach ($item in $items)
                {
                $itemCount ++
                Write-Progress -Activity "Apply retention tag to $DefaultFolder" -CurrentOperation "Updating item $itemCount of $totalItems" -PercentComplete ($itemCount/$totalItems*100) -Status ' '
            	$policyTagProperty = New-Object -TypeName Microsoft.Exchange.WebServices.Data.ExtendedPropertyDefinition(0x3019,[Microsoft.Exchange.WebServices.Data.MapiPropertyType]::Binary)
				$policyTagGUID = New-Object -TypeName Guid($personalTagGUID)
               	$item.SetExtendedProperty($policyTagProperty, $policyTagGUID.ToByteArray())
                $item.SetExtendedProperty($retentionPeriodProperty, $personalTagRetentionDays)
				$retentionDate = New-Object -TypeName Microsoft.Exchange.WebServices.Data.ExtendedPropertyDefinition(0x301C,[Microsoft.Exchange.WebServices.Data.MapiPropertyType]::SystemTime)
				$item.SetExtendedProperty($retentionDate, $item.DateTimeCreated.AddDays($personalTagRetentionDays))
				#Include enum to not send updates; okay to use even when not a meeting
				$item.Update([Microsoft.Exchange.WebServices.Data.ConflictResolutionMode]::AlwaysOverwrite,[Microsoft.Exchange.WebServices.Data.SendInvitationsOrCancellationsMode]::SendToNone)
                }
		
		Write-Host $totalItems "items processed in $($DefaultFolder)."
        }
    }

if (-not($EXOCreds))
    {
    $EXOCreds = Get-Credential -Message 'Enter the credentials to use to access the mailbox.' -UserName $EmailAddress
    }
Apply-RetentionTag $EmailAddress

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

179

180

181

182

183

184

185

186

187

188

189

190

191

192

193

194

195

196

197

198

199

200

201

202

203

204

205

206

207

208

209

210

211

#Apply retention tag to items in deleted items folder that do not have one

#1.6.1 Added policy GUID back to EXO mailboxes (issue resolved in service)

#1.6 Updated for changes in EXO, change loop to get all items and then update all items,

# added parameters for target environment and impersonation

#1.5 Added option of updating items that already have a tag

#1.4 Added choice of tag to apply

#1.3 Fixed processing of calendar items

#1.2 Update calendar items that can be, note the count that cannot be

#1.1.2 Prefill cred username with email address of target mailbox

.Synopsis

Assign personal tag to all items in a default folder.

.Description

Get all items in a folder that do not have a retention tag explicitly

assigned and assign a personal tag them.

.Parameter EmailAddress

Email address of mailbox to process

.Parameter DefaultFolder

The name of the default folder to process. Default value is DeletedItems.

.Parameter DaysToRetain

Number of days to retain an item for. Must match one of the defined

personal tags in the Variables region.

.Parameter OverwriteExistingTags

Switch to indicate that items with a tag that does not match the tag to be assigned

are updated. The default is to update only items that do not have a tag.

.Parameter Environment

Specify whether the target environment is Exchange Online or Exchange on-premises.

The default is Exchange Online.

.Parameter UseImpersonation

Switch to indicate impersonation should be used instead of full or delegate access.

.Example

Set-DefaultFolderItemsTag.ps1 user@domain

.Example

Set-DefaultFolderItemsTag.ps1 user@domain -DefaultFolder SentItems -DaysToRetain 365

.Notes

Version: 1.6.1

Date: 12/1/17

Param (

[Parameter(Position=0,Mandatory=$true,HelpMessage="Email address of mailbox")][string]$EmailAddress,

[Parameter(Position=1,Mandatory=$false,HelpMessage="Name of default folder to process")]

[ValidateSet('Calendar','ConversationHistory','DeletedItems','Inbox','Journal','JunkEmail','Notes','SentItems','SyncIssues','Tasks')]

[string]$DefaultFolder = 'DeletedItems',

[Parameter(Position=2,Mandatory=$true)][ValidateSet(30,365)][int]$DaysToRetain,

[ValidateSet('Online','OnPremises')]$Environment = 'Online',

[switch]$UseImpersonation,

[switch]$OverwriteExistingTags

)

#Region Variables

#Replace with GUIDs of tag to assign to items and the number of days each tag retains items

$30DayTag = '{33CEDA03-0536-424C-8ECA-E839E0BC5945}',30

$365DayTag = '{AE331EBC-934F-43E2-8AB9-8480CE98E457}',365

#EndRegion

switch ($DaysToRetain)

{

$personalTagGUID = $30DayTag[0]

$personalTagRetentionDays = $30DayTag[1]

}

365

{

$personalTagGUID = $365DayTag[0]

$personalTagRetentionDays = $365DayTag[1]

}

#Check for EWS API

$apiPath = (($(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 $apiPath)

{

Add-Type -Path $apiPath

}

else

{

Write-Error "The Exchange Web Services Managed API is required to use this script." -Category NotInstalled

break

}

function Connect-WebServices ($smtpAddress, $folder)

{

$exchangeVersion = [Microsoft.Exchange.WebServices.Data.ExchangeVersion]::Exchange2013_SP1

$exchangeService = New-Object -TypeName Microsoft.Exchange.WebServices.Data.ExchangeService($exchangeVersion)

$exchangeService.Credentials = New-Object -TypeName Microsoft.Exchange.WebServices.Data.WebCredentials($EXOCreds)

#Use hard-coded URL

$exchangeService.Url = 'https://outlook.office365.com/EWS/Exchange.asmx'

#Enable tracing to debug

#$exchangeService.TraceEnabled = $true

if ($UseImpersonation)

{

$exchangeService.ImpersonatedUserId = New-Object -TypeName Microsoft.Exchange.WebServices.Data.ImpersonatedUserId([Microsoft.Exchange.WebServices.Data.ConnectingIdType]::SmtpAddress, $smtpAddress)

}

$folderID = New-Object -TypeName Microsoft.Exchange.WebServices.Data.FolderId([Microsoft.Exchange.WebServices.Data.WellKnownFolderName]::$folder,$smtpAddress)

[Microsoft.Exchange.WebServices.Data.Folder]::Bind($exchangeService,$folderID)

}

function Apply-RetentionTag

{

#Bind to folder of mailbox

$folder = Connect-WebServices -smtpAddress $EmailAddress -folder $DefaultFolder

if (-not($folder))

{

Write-Error -Message "Error binding to folder in mailbox for $EmailAddress." -Category ConnectionError

}

else

{

$pageSize = 50

$offset = 0

$moreItems = $true

$items = $null

$firstRun = $true

while ($moreItems)

{

if ($firstRun)

{

$percentComplete = -1

}

else

{

$percentComplete = $items.Count/$totalItems*100

Write-Verbose -Message "$($items.Count) of $totalItems have been retrieved."

}

if ($OverwriteExistingTags)

{

Write-Progress -Activity "Apply retention tag to $DefaultFolder" -CurrentOperation "Retrieving all items in folder" -PercentComplete $percentComplete -Status ' '

}

else

{

Write-Progress -Activity "Apply retention tag to $DefaultFolder" -CurrentOperation "Retrieving items with no tag" -PercentComplete $percentComplete -Status ' '

}

#Set up paged search to stay below FindCountLimit

$itemView = New-Object -TypeName Microsoft.Exchange.WebServices.Data.ItemView($pageSize,$offset,[Microsoft.Exchange.WebServices.Data.OffsetBasePoint]::Beginning)

$itemView.Traversal = [Microsoft.Exchange.WebServices.Data.ItemTraversal]::Shallow

$itemView.PropertySet = New-Object -TypeName Microsoft.Exchange.WebServices.Data.PropertySet([Microsoft.Exchange.WebServices.Data.BasePropertySet]::IdOnly)

$itemView.PropertySet.Add([Microsoft.Exchange.WebServices.Data.ItemSchema]::DateTimeCreated)

#Property that contains the number of days for the applied tag

$retentionPeriodProperty = New-Object -TypeName Microsoft.Exchange.WebServices.Data.ExtendedPropertyDefinition(0x301A,[Microsoft.Exchange.WebServices.Data.MapiPropertyType]::Integer)

$itemView.PropertySet.Add($retentionPeriodProperty)

if ($OverwriteExistingTags) #Get all items, regardless of whether tag is applied

{

$itemSearchResult = $folder.FindItems($itemView)

}

else

{

#Create the search filter to find items with no retention period applied

$itemSearchFilter = New-Object -TypeName Microsoft.Exchange.WebServices.Data.SearchFilter+Exists($retentionPeriodProperty)

$itemSearchFilterNot = New-Object -TypeName Microsoft.Exchange.WebServices.Data.SearchFilter+Not($itemSearchFilter)

$itemSearchResult = $folder.FindItems($itemSearchFilterNot,$itemView)

}

if ($firstRun)

{

if ($itemSearchResult.TotalCount -eq 0)

{

Write-Host "There are no items to process in $($DefaultFolder)."

exit

}

else

{

Write-Verbose -Message "Initial search results total item count: $($itemSearchResult.TotalCount)"

$totalItems = $itemSearchResult.TotalCount

$firstRun = $false

}

$items += $itemSearchResult.Items

if ($itemSearchResult.MoreAvailable -eq $false)

{

$moreItems = $false

Write-Verbose -Message "More items is set to False."

}

if ($moreItems)

{

$offset += $pageSize

Write-Verbose -Message "Offset is $offset."

}

#Process each item in search result collection

$itemCount = 0

foreach ($item in $items)

{

$itemCount ++

Write-Progress -Activity "Apply retention tag to $DefaultFolder" -CurrentOperation "Updating item $itemCount of $totalItems" -PercentComplete ($itemCount/$totalItems*100) -Status ' '

$policyTagProperty = New-Object -TypeName Microsoft.Exchange.WebServices.Data.ExtendedPropertyDefinition(0x3019,[Microsoft.Exchange.WebServices.Data.MapiPropertyType]::Binary)

$policyTagGUID = New-Object -TypeName Guid($personalTagGUID)

$item.SetExtendedProperty($policyTagProperty, $policyTagGUID.ToByteArray())

$item.SetExtendedProperty($retentionPeriodProperty, $personalTagRetentionDays)

$retentionDate = New-Object -TypeName Microsoft.Exchange.WebServices.Data.ExtendedPropertyDefinition(0x301C,[Microsoft.Exchange.WebServices.Data.MapiPropertyType]::SystemTime)

$item.SetExtendedProperty($retentionDate, $item.DateTimeCreated.AddDays($personalTagRetentionDays))

#Include enum to not send updates; okay to use even when not a meeting

$item.Update([Microsoft.Exchange.WebServices.Data.ConflictResolutionMode]::AlwaysOverwrite,[Microsoft.Exchange.WebServices.Data.SendInvitationsOrCancellationsMode]::SendToNone)

}

Write-Host $totalItems "items processed in $($DefaultFolder)."

}

if (-not($EXOCreds))

{

$EXOCreds = Get-Credential -Message 'Enter the credentials to use to access the mailbox.' -UserName $EmailAddress

}

Apply-RetentionTag $EmailAddress

| Next in series

Delegate management module updated to v1.4.5

Posted on February 18, 2015 by Scott — No Comments ↓

Articles in the "Mailbox Delegate Management" series

Super duper delegate retrieval script
PowerShell module for managing Exchange mailbox delegates
Small update to delegate management module
Delegate management module updated to v1.3.5
Delegate management module updated to support Exchange Online
Delegate management module updated to v1.4.5 [This article]
Delegate management module updated to 1.4.6
Delegate management module updated to v1.5.0
Delegate management module updated

The module has been updated mostly for fixing issues when working with Exchange Online. The first version that supported it didn’t account account for object properties that are different compared to on-premises, as well as how to get user information. These are the changes in this version:

Fixed when using a default connection mode of EXO so that the rest of the module knows it.
Added option to not use autodiscover when using EXO since those lookups can sometimes add a lot of time to the cmdlets running. If default mode is EXO and you don’t want to use autodiscover, uncomment that line below the default mode. If using EXO on-demand, you can set the option with the DoNotUseAutodiscover switch parameter of Set-DelegateManagementMode. (The cmdlet’s help has been updated to reflect this.)
Added usage of the Azure Active Directory module when using EXO mode. This means you need to have the WAAD module installed to work against Exchange Online. Since that module is 64-bit only, you can only run the delegate management module in a 64-bit PowerShell session.
Fixed (hopefully and finally) the Write-Progress prompt that some people were getting that interrupted the cmdlets. (Thanks, Jim.)
Fixed getting Send As permission in EXO due to it using a different cmdlet.
Fixed getting folder permissions in EXO due to the object properties being different.
Added removal of Deleted Items and Sent Items folder permissions when removing a delegate.

There are other things I have discovered need fixing: Exchange cmdlets loaded by the module are not accessible outside of the module; Exchange cmdlet errors are not caught in PowerShell 4 so the module cmdlets keep running after a terminating error would be detected if running in PowerShell 2; if multiple objects are pipelined to Get-MailboxDelegate and one of them does not have a mailbox, the cmdlet terminates without processing the remaining objects in the pipeline.

I also still intend to add support for hybrid mode. It is more complicated, though, such as with adding delegates since I need to account for attempts at cross-premises delegation, which isn’t supported.

DelegateManagement.zip (9.2 KiB)

Previous in series | | Next in series

Delegate management module updated to support Exchange Online

Posted on October 2, 2014 by Scott — 7 Comments ↓

Articles in the "Mailbox Delegate Management" series

Super duper delegate retrieval script
PowerShell module for managing Exchange mailbox delegates
Small update to delegate management module
Delegate management module updated to v1.3.5
Delegate management module updated to support Exchange Online [This article]
Delegate management module updated to v1.4.5
Delegate management module updated to 1.4.6
Delegate management module updated to v1.5.0
Delegate management module updated

The module for managing Exchange mailbox delegates has been updated with support for Exchange Online. In its current version (v1.4) you can use one mode or the other. The default mode is on-premises, but you can change this on demand to use Exchange Online by using Set-DelegateMananagementMode, a new cmdlet added in this version. If you change it on demand, you will be prompted for your Office 365 credentials. If you will be exclusively working with Exchange Online, you can change the line near the top of the module to default to using that method. In that case, you will be prompted for credentials the first time you run a cmdlet.

It is my intention to update the module to support a hybrid environment, but I first need to set up one in my lab in order to test it.

Previous in series | | Next in series

Database seeding completion estimate script updated

Posted on November 22, 2013 by Scott — No Comments ↓

Articles in the "Database seeding estimation" series

Estimate the time to complete seeding a mailbox database copy
Database seeding completion estimate script updated [This article]

The script has been updated to include the average throughput from the sampling duration in the output. This will help gauge why the seeding completion time may vary between multiple executions of the script, such as during vs. outside of business hours. Additionally, some variable names have been updated (to better reflect their contents), and per scripting best practices, the help has an added example so that all parameters are used at least once among all the examples. The inline code has been updated, as has the download.

Get-DatabaseSeedingCompletion.zip (1.5 KiB)

Previous in series |

sidefumbling

The consequence of not having six hydrocoptic marzelvanes fitted to the ambifacient lunar waneshaft.

Author Archives: Scott

Rename Outlook attachments before you send them

Script to set retention tag on default folder items updated to v1.1.1

Articles in the "Retention tag on default folder items" series

Use EWS to apply retention policy to items in a default folder

Articles in the "Retention tag on default folder items" series

Delegate management module updated to v1.4.5

Articles in the "Mailbox Delegate Management" series

Delegate management module updated to support Exchange Online

Articles in the "Mailbox Delegate Management" series

Database seeding completion estimate script updated

Articles in the "Database seeding estimation" series