Summary

This script allows you to search a mailbox for messages and by default will write the items to the pipeline. This allows the messages to be collected into a PowerShell variable and queried. While primarily for searching messages and returning the results, the script can also delete any matched items or update the message class (e.g. change it from IPM.Note.Custom back to IPM.Note). If no folders are specified (using the appropriate parameters), then the Inbox will be processed.

To make bulk changes to items (which includes delete), please use the Update-FolderItems.ps1 script. Also note that the Search-Mailbox cmdlet can also search and delete (and can search on recipients, which this script doesn't implement).

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

Examples

Change all Inbox items of message class IPM.Note.Custom to IPM.Note (EXO)

.\Search-MailboxItems.ps1 -Mailbox $Mailbox -MessageClass "IPM.Note.Custom" -NewMessageClass "IPM.Note" -Office365 -OAuth -OAuthTenantId $tenantId -OAuthClientId $clientId

The above will search for all items in the Inbox of message class IPM.Note.Custom and change them to IPM.Note.

Collect a list of all items of class IPM.Note.Custom (EXO)

$customItems = .\Search-MailboxItems.ps1 -Mailbox $Mailbox -IncludeFolderList @("WellKnownFolderName.MsgFolderRoot") -ProcessSubfolders -MessageClass "IPM.Note.Custom" -Office365 -OAuth -OAuthTenantId $tenantId -OAuthClientId $clientId

The above will search for all IPM.Note.Custom items in the whole mailbox and pipes the matches to a PowerShell variable.

Find all items in a mailbox from specific sender

.\Search-MailboxItems.ps1 -Mailbox $Mailbox -IncludeFolderList @("WellKnownFolderName.MsgFolderRoot") -ProcessSubfolders -Sender "[email protected]" -Office365 -OAuthTenantId $tenantId -OAuthClientId $clientId -OAuthSecretKey $secretKey

The above will search for all messages received from a specific sender over the entire mailbox.

Delete all items in a mailbox from specific sender

.\Search-MailboxItems.ps1 -Mailbox $Mailbox -IncludeFolderList @("WellKnownFolderName.MsgFolderRoot") -ProcessSubfolders -Sender "[email protected]" -Delete -Office365 -OAuthTenantId $tenantId -OAuthClientId $clientId -OAuthSecretKey $secretKey

The above will search for all messages received from a specific sender over the entire mailbox, and delete any found. The delete will be a move to Deleted Items (unless the items are found in the Deleted Items folder, in which case it will be a soft delete). The -HardDelete parameter can be used to hard delete the item (see documentation here).

Delete items within Inbox and subfolders from specific sender and more than 30 days old

.\Search-MailboxItems.ps1 -Mailbox $Mailbox -IncludeFolderList @("WellKnownFolderName.Inbox") -ProcessSubfolders -Sender "[email protected]" -CreatedBefore $([DateTime]::Today.AddDays(-30)) -Delete -Office365 -OAuthTenantId $tenantId -OAuthClientId $clientId -OAuthSecretKey $secretKey

The above will search the Inbox and subfolders for messages received from a specific sender and created more than 30 days ago. The delete will be a move to Deleted Items (unless the items are found in the Deleted Items folder, in which case it will be a soft delete). The -HardDelete parameter can be used to hard delete the item (see documentation here).

Parameters

-Mailbox: Specifies the mailbox to be accessed..

-Archive: If this switch is specified, items will be searched for in the archive mailbox (otherwise, the main mailbox is searched).

-AssociatedItemsOnly: If this switch is specified, only associated items will be searched (see Traversal Attribute Values).

-ProcessSubfolders: If this switch is specified, then subfolders of any specified folder will also be searched.

-IncludeFolderList: Specifies the folder(s) to be searched (if not present, then the Inbox folder will be searched). Any exclusions override this list.

-ExcludeFolderList: Specifies the folder(s) to be excluded (these folders will not be searched).

-DoNotOutputMatches: If set, matching items will not be written to the pipeline (but any specified actions will be taken).

-MessageClass: Specifies the message class of the items being searched.

-CreatedBefore: If specified, only messages created before this date will be matched.

-CreatedAfter: If specified, only messages created after this date will be matched.

-Subject: If specified, items will match if the subject contains this string.

-Sender: Will match only items with the specified sender.

-SenderDisplayName: Will match only items with the specified sender display name. If Sender is also specified, then Sender must also match.

-MessageId: Only item(s) with this MessageId will be matched.

-ViewProperties: Adds the given property(ies) to the list of those that will be retrieved for an item (must be supplied as hash table @{}). By default, Id, Subject and Sender are retrieved.

-NewMessageClass: Specifies the new message class that will be applied to the items (note that you cannot change the base item class of an item).

-Delete: If this switch is specified, matching items will be deleted (moved to Deleted Items).

-HardDelete: If this switch is specified, matching items will be hard-deleted.

-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.