Outlook Email Mover

September 22, 2024bytheDXT

The way I manage my email might seem a bit strange. Due to working in IT, I get lots of emails. Some emails need action, some are regular emails, and some are notifications I want to know about as soon as they happen. I feel like a normal person would make an Outlook rule to move emails into folders and just check those folders when needed.

The problem I have with dumping emails into folders automatically is when I only have my phone on me, I won’t know if a new email comes in when it’s auto-moved to a folder, so I’d have to keep checking the folders, and that doesn’t work with my workflow.

An example is I get notifications when backups run. If a backup is successful, I have an activated Outlook rule that moves the email into a folder. However, if a backup has an issue or something like that, I want it in my inbox so I see it immediately, no matter what device I’m using.

After I’ve addressed the email, I could move it into a folder. But that is a manual step, I’d rather have an automated way. Also, it doesn’t scale well if you get a lot of emails, and due to the nature of IT and alerts, I get lots of emails for all sorts of things that I want to see, but after I’ve read the email, I want the email to get filed away correctly.

I used to select blocks of emails and move them into folders. However, I’ve accidentally moved an email I needed to reply to into a folder and didn’t notice. If I don’t have a way to move the emails around, an email I need to action could also get lost in the noise of other emails.

A normal person might say to use a different system for alerts. While that’s valid, the issue I have is that’s another system that I’d need to keep checking when I’m not in front of a computer, and I don’t want to do that because I am stubborn and my current system does work, which is why I prefer email notifications.

I expressed the issue of my email clutter to a friend, and they told me about a system they’ve been using to help with it. They use Outlook rules that aren’t enabled to move emails around to different folders. They trigger the rules by using a macro in Outlook.

I tried the Outlook rules macro option, and it worked wonderfully with the one catch you need to enable macros in Outlook. I am worried that having macros enabled in Outlook will increase the attack surface for my account.

Rather than using macros, I found a way to do the same thing but with PowerShell and com objects. This works great, but you have to have Outlook open for it to work, and it doesn’t work with New Outlook. Currently, there doesn’t seem to be any support for com objects in New Outlook.

I went down the rabbit hole of figuring out how I could upgrade the script to support moving emails without using com objects. The rabbit hole led me to Microsoft Graph. With Microsoft Graph, there is a way to retrieve a user’s Outlook rules, but there doesn’t appear to be a way to execute the rules on demand like the macro and com object methods did.

However, Microsoft Graph does support moving emails around. Most of the Outlook rules I use to move emails around are basic rules that can be easily rebuilt using Microsoft Graph. I now have a script that I’m calling Outlook Email Mover that moves emails around based on some provided parameters, which is exactly what an Outlook rule does.

The Script

Outlook Email Mover uses Microsoft Graph to connect to the user’s mailbox and move emails around.

You can find the script on my GitHub https://github.com/thedxt/Outlook-Email-Mover

Prerequisites

Microsoft Graph installed and configured. If you don’t know how to do that. Here’s my blog post about the Microsoft 365 Setup for Microsoft Graph PowerShell SDK.

How It Works

Outlook Email Mover uses Microsoft Graph to connect to a user’s mailbox. The required scope is "Mail.ReadWrite".

Inside the Outlook Email Mover script is a function called Outlook-email-mover-connector.

The Outlook email mover connector is a function you can use to connect to Microsoft Graph. You can also connect to Microsoft Graph yourself and not use the function as it is optional.

The Outlook Email Mover Connector has two connect modes CLI and Entra App.

Selecting CLI connect mode will call the Connect-MgGraph command to connect to Microsoft Graph with the required scope.

If you select the EntraApp connect mode, you must provide the Entra App ID and your Tenant ID to connect. It will connect as your account to the Entra Application with the required scope and will use delegated permissions to execute the command you want against your mailbox.

Once connected to Microsoft Graph, you can fully use the Outlook Email Mover function.

Here are the parameters available for Outlook Email Mover.

user: This will be your UPN. This is required.
source_folder: The name of the source folder from which you want to move emails. Typically, this is just Inbox. This is required.
dest_root_folder: The name of the destination folder to which you want the emails moved. This is required.
dest_sub_folder: The name of the destination sub-folder if you want the emails moved to a sub-folder. This parameter is optional, and if used, it must be a sub-folder in the root folder.
sender: The email address that sent the email. This is used to help make sure only the emails you intend to move are moved.
subject: The subject line of the emails you want to target.
dryrun: This is an optional setting and will output the emails that would be moved.

When you run Outlook Email Mover, it starts by determining the source and destination folder IDs. If you provide a sub-folder, it will use the id of the root destination folder to find the id for the sub-folder.

Next, it builds the filter parameters that will be used to find the emails. It uses contains for the sender address and the subject line and uses the and condition to combine them.

Outlook Email Mover then searches for the emails in the source folder.

If the dry run parameter is active, it will only output the emails the search found. The emails are sorted by received date, which is in UTC.

If the dry run parameter is inactive, it will move the emails and output which email it moved and to which location.

Example

I want to find all the GoDaddy Renewal Notice Emails and move them to my Deleted Items.

I would run Outlook Email Mover with the following command

Outlook-email-mover -user "[email protected]" -source_folder "Inbox" -dest_root_folder "Deleted Items" -sender "[email protected]" -subject "Your GoDaddy Renewal Notice" -dryrunCode language: PowerShell (powershell)

Here is an example of the output.

If I’m confident I will not accidentally move the wrong things, I will remove the dryrun parameter and run it for real.

Outlook-email-mover -user "[email protected]" -source_folder "Inbox" -dest_root_folder "Deleted Items" -sender "[email protected]" -subject "Your GoDaddy Renewal Notice"Code language: PowerShell (powershell)