Summary

Update-FolderItems.ps1 is a PowerShell script that uses EWS (requires the EWS Managed API) to update items within a mailbox. It can be used for multiple folders, and automated against multiple mailboxes. The script handles throttling and so works against large Office 365 mailboxes.

The below examples assume that the Azure AD application registration details have been stored in PowerShell variables e.g.

$Mailbox = "[email protected]"
$clientId = "Application Id"
$tenantId = "Tenant Id"
$secretKey = "Secret key" # App only auth
$redirectUrl = "http://localhost/" # Delegate auth

Examples

Exchange Online

Accept all pending meeting requests that don't have a conflict, and decline those that do

The below code will process any pending calendar invitations in the specified mailbox and accept any that have no conflicts (any others will be declined). Certificate authentication is used in this example.

.\Update-FolderItems.ps1 -Mailbox $Mailbox -FolderPath "WellKnownFolderName.Inbox" -AcceptCalendarInvite -DeclineCalendarInviteIfConflict -Office365 -OAuth -OAuthTenantId $tenantId -OAuthClientId $clientId -OAuthCertificate $certificate

Accept all pending meeting requests that don't have a conflict, replacing the subject of accepted meeting with Organiser name

The code below will process any pending calendar invitations in the specified mailbox and accept any that have no conflicts (any others will be declined). The accepted meeting will have the subject replaced by the organizer name (this only affects the meeting in the mailbox in which it was accepted) - similar to calendar assistant processing. Certificate authentication is used in this example.

.\Update-FolderItems.ps1 -Mailbox $Mailbox -FolderPath "WellKnownFolderName.Inbox" -AcceptCalendarInvite -DeclineCalendarInviteIfConflict -DeleteSubject -AddOrganizerToSubject -Office365 -OAuth -OAuthTenantId $tenantId -OAuthClientId $clientId -OAuthCertificate $certificate

Remove contact photos from all contacts

The code below will remove any contact photos from items in the Contacts folder of the mailbox.

.\Update-FolderItems.ps1 -Mailbox $Mailbox -FolderPath "WellKnownFolderName.Contacts" -Office365 -OAuth -OAuthTenantId $tenantId -OAuthClientId $clientId -OAuthRedirectUri $redirectUrl -DeleteContactPhoto

Update PR_SENSITIVITY and PR_RECIPIENT_REASSIGNMENT_PROHIBITED

The code below will search for any items that have PR_SENSITIVITY (MAPI property 0x0036003) set to a value of 2, and for those items it will set PR_SENSITIVITY to 0 and PR_RECIPIENT_REASSIGNMENT_PROHIBITED (MAPI property 0x002B00B) to false. In this case, as -WhatIf is specified, no changes will be written - run without -WhatIf to make changes.

.\Update-FolderItems.ps1 -Mailbox $Mailbox -FolderPath "WellKnownFolderName.Inbox" -Office365 -OAuth -OAuthTenantId $tenantId -OAuthClientId $clientId -OAuthRedirectUri $redirectUrl -PropertiesMustMatch @{"0x00360003" = 2} -AddItemProperties @{"0x00360003" = 0; "0x002B000b" = $false } -WhatIf

List all items that have a specific retention policy applied

$items = .\Update-FolderItems.ps1 -Mailbox $Mailbox -FolderPath "WellKnownFolderName.Inbox" -Office365 -OAuth -OAuthTenantId $tenantId -OAuthClientId $clientId -OAuthRedirectUri $redirectUrl -PropertiesMustExist @("0x30190102" ) -ListMatches
$items.Subject

The above will search for any items that have a retention policy applied (they have PR_POLICY_TAG present) and then output the subject of those items. The $items variable in this case captures all matching items, so you can also query other properties e.g. $items.Id.

Delete the autocomplete cache from a mailbox

.\Update-FolderItems.ps1 -Mailbox $Mailbox -FolderPath "WellKnownFolderName.Root" -AssociatedItems -Office365 -OAuth -OAuthTenantId $tenantId -OAuthClientId $clientId -OAuthRedirectUri $redirectUrl -PropertiesMustMatch @{"0x001A001F" = "IPM.Configuration.OWA.AutocompleteCache"} -Delete

The above will delete the AutoComplete cache message from a mailbox (which will remove the Outlook email address cache). Note that the message that needs to be deleted in Exchange On-premises is different (see example 10).

Delete all messages where any recipient is not from one of the listed domains

.\Update-FolderItems.ps1 -Mailbox $Mailbox -FolderPath "WellKnownFolderName.Inbox" -Office365 -OAuth -OAuthTenantId $tenantId -OAuthClientId $clientId -OAuthRedirectUri $redirectUrl -RecipientsNotFromDomains @("domain1.co.uk", "domain2.com", "domain3.com") -Delete -WhatIf

The above will delete (if -WhatIf is removed) any message that has a recipient that is NOT included in the list of domains.

Retrieve all messages where recipients are not from specific domains

$items = .\Update-FolderItems.ps1 -Mailbox $Mailbox -FolderPath "WellKnownFolderName.MsgFolderRoot" -ProcessSubfolders -Office365 -OAuth -OAuthTenantId $tenantId -OAuthClientId $clientId -OAuthRedirectUri $redirectUrl -RecipientsNotFromDomains @("domain1.co.uk", "domain2.com", "domain3.com") -ListMatches
$items | select subject | ft

The above will retrieve all messages (it searches the whole mailbox) that have recipients who are NOT from the listed domains. The list of matching messages is stored in $items, which is then used to show a list containing the subject of each message. OAuth is used to log on (works with MFA) - the tenant Id must be specified, and the script will require consent.

Resend messages

.\Update-FolderItems.ps1 -Mailbox $Mailbox -FolderPath "WellKnownFolderName.Inbox\Resend" -Office365 -OAuth -OAuthTenantId $tenantId -OAuthClientId $clientId -OAuthSecretKey $secretKey -Resend -ResendToForInReceivedHeader -ResendFrom "[email protected]" -ResendPrependText "This message (originally sent from <!-- %ORIGINALSENDER% --> to <!-- %ORIGINALRECIPIENTS% --> at <!-- %ORIGINALSENTTIME% -->) has been resent by an unmonitored mailbox." -ResendUpdatePrependTextFields -ResendCreateDraftOnly -SenderNotFromAddresses @("[email protected]") -MaximumNumberOfItemsToProcess 10 -Impersonate

The above will process the folder \Inbox\Resend and resend any items found within it that were not sent by [email protected]. A message is prepended to the message being resent (the fields will be replaced with the relevant data from the message). In this case the message won't be sent, it will only be saved as a Draft (for testing purposes). Only the first ten items will be processed (after which the script will go into -WhatIf mode and report only).

Delete IPM.Note items create before a specific date

.\Update-FolderItems.ps1 -Mailbox [email protected] -ProcessSubfolders -Office365 -OAuth -OAuthTenantId $tenantId -OAuthClientId $clientId -OAuthRedirectUri $redirectUrl -PropertiesMustMatch @{"0x001A001F" = "IPM.Note"} -CreatedBefore "01/01/2020" -Delete -WhatIf

The above will find all email messages (items of message class IPM.Note) that were created before 1/1/2020 and delete them (if -WhatIf is removed).

Exchange On-premises

Delete all rules set on public folders

.\Update-FolderItems.ps1 -Mailbox [email protected] -AssociatedItems -PublicFolders -ProcessSubfolders -EwsUrl "https://e1.e19.local/EWS/Exchange.asmx" -Credential (Get-Credential) -PropertiesMustMatch @{"0x001A001F" = "IPM.Rule.Version2.Message"} -Delete  -HardDelete

The above will find and delete all rules set on public folders in an Exchange On-premises environment. Note that the authenticating account must have Owner rights over all the public folders for this to work.

Delete Outlook autocomplete cache

$c = Get-Credential # Authenticate as user with ApplicationImpersonation permissions to target mailbox
$Mailbox = "[email protected]"
.\Update-FolderItems.ps1 -Credential $c -Mailbox $Mailbox -FolderPath "WellKnownFolderName.Inbox" -AssociatedItems -EwsUrl "https://e1.e19.local/EWS/Exchange.asmx" -PropertiesMustMatch @{"0x001A001F" = "IPM.Configuration.Autocomplete"} -Impersonate -Delete -HardDelete

This will delete the Outlook autocomplete cache from the mailbox (equivalent to starting Outlook with /CleanAutoCompleteCache switch).

Parameters

-Mailbox: Specifies the source mailbox (from which items will be moved/copied).

-Archive: When specified, the archive mailbox will be accessed (instead of the main mailbox).

-PublicFolders: If this switch is present, folder path is required and the path points to a public folder.

-FolderPath: Folder to search - if omitted, the mailbox message root folder is assumed.

-ProcessSubfolders: When specified, subfolders will also be processed.

-AssociatedItems: When specified, hidden (associated) items of the folder are processed (normal items are ignored).

-AddItemProperties: Adds the given property(ies) to the item(s) (must be supplied as hash table @{}).

-DeleteItemProperties: Deletes the given property(ies) from the item(s).

-AcceptCalendarInvite: Accepts any matching appointment requests.

-DeclineCalendarInviteIfConflict: Performs a check for conflicts before accepting a meeting (if there is a conflict, the meeting will be declined). Must be used with -AcceptCalendarInvite.

-DeleteSubject: If specified, the subject is removed from the appointment (only for the accepted meeting).

-AddOrganizerToSubject: If specified, the organizer is appended to the appointment subject (only for the accepted meeting).

-DeclineCalendarInvite: Declines any matching appointment requests.

-MarkAsRead: Marks the item(s) as read.

-MarkAsUnread: Marks the item(s) as unread.

-MatchContactAddresses: Actions will only apply to contact objects that have the given SMTP address as their email address. Supports multiple SMTP addresses passed as an array.

-Resend: Resends the message (resend options must also be set).

-ResendCreateDraftOnly: Creates a draft of the message that will be resent (in the Drafts folder of the mailbox). Message will not be sent.

-ResendFrom: Sets the sender for the resent message.

-ResendPrependText: Prepends the provided text to the resent message body.

-ResendUpdatePrependTextFields: If this switch is present, the text to be prepended will be modified per field values. e.g. <!-- %ORIGINALSENDER% --> will be replaced with the original sender email (other fields are <!-- %ORIGINALRECIPIENTS% --> and <!-- %ORIGINALSENTTIME% -->).

-ResendToForInReceivedHeader: Resends the message to the recipient declared in the message Received: header (if present).

-DeleteContactPhoto: If any matching contact object contains a contact photo, the photo is deleted.

-Delete: Deletes the item(s).

-HardDelete: When used with -Delete (has no effect otherwise), forces a hard delete of the item(s).

-SearchFilter: If specified, only items that match the given AQS filter will be moved (see https://learn.microsoft.com/en-us/exchange/client-developer/exchange-web-services/how-to-perform-an-aqs-search-by-using-ews-in-exchange).

-RecipientsNotFromDomains: If specified, only items that have recipients not from the listed domains will be matched.

-RecipientsFromDomains: If specified, only items that have recipients from the listed domains will be matched.

-RecipientsNotFromAddresses: If specified, only items that have recipients not from the listed addresses will be matched.

-ExcludeCCRecipients: If specified, CC recipients will not be checked for domain or email address matches.

-SenderNotFromDomains: If specified, only items where the sender is not from one of the listed domains will be matched.

-SenderFromDomains: If specified, only items where the sender is from one of the listed domains will be matched.

-SenderNotFromAddresses: If specified, only items where the sender is not from one of the listed addresses will be matched.

-CreatedAfter: Only processes items created after this date.

-CreatedBefore: Only processes items created before this date.

-PropertiesMustExist: If specified, only items that have values in the given properties will be updated.

-PropertiesMustMatch: If specified, only items that match the given values in the given properties will be updated. Properties must be supplied as a Dictionary @{"propId" = "value"}.

-ListMatches: Outputs any matching items (can be collected for further processing).

-LoadItemsIndividually: If set, a separate GetItem request is sent to retrieve each item. Much slower (batch processing is used otherwise), but may need to be used if querying large properties.

-MaximumNumberOfItemsToProcess: If this is set to any value higher than 0, then the script will go into -WhatIf mode once that many items have been processed.

-Credential: Credentials used to authenticate with EWS (provided as PSCredential).

-OAuth: when specified, will use OAuth to access the mailbox (required for MFA enabled accounts).

-OAuthClientId: The application Id as registered in Azure AD. If not specified, a global registration will be used that supports delegated access only (and will need consent to be able to access mailboxes).

-OAuthTenantId: The tenant Id in which the application is registered. If missing, application is assumed to be multi-tenant and the common log-in URL will be used.

-OAuthRedirectUri: The redirect Uri of the Azure registered application (defaults to http://localhost/code).

-OAuthSecretKey: Secret key to be used when obtaining access token. If this is specified, then application permissions are requested and no user log-on will be required.

-OAuthCertificate: The OAuth certificate to be used when obtaining access token (requires MSAL dll). Application permissions are requested in this scenario. You can obtain a certificate from your own certificate store using the thumbprint: Get-Item Cert:\CurrentUser\My\50B510B4AE120D9B0EE3F059B6DD494469CD6D3B.

-Impersonate: If set, ApplicationImpersonation is used to access the mailbox(es).

-EwsUrl: EWS Url (if omitted, and -Office365 not specified, then autodiscover is used).

-Office365: If set, requests are directed to Office 365 endpoint (overrides -EwsUrl).

-ForceTLS12: If specified, only TLS 1.2 connections will be negotiated.

-EWSManagedApiPath: Path to managed API (if omitted, a search of standard paths is performed).

-IgnoreSSLCertificate: If set, invalid SSL certificates will be ignored and the connection made regardless. Use with care, required for self-signed certificates.

-AllowInsecureRedirection: If set, insecure redirection will be allowed during AutoDiscover.

-LogFile: Logs script activity to the specified file.

-TraceFile: Write all EWS traffic (requests/responses/headers) to the specified file.

-WhatIf: If set, no changes will be made to the target mailbox (but actions that would be taken will be logged).