# ——————————————————————-
# 1. INITIALISATION & INSTRUCTIONS
# ——————————————————————-
Write-Host “================================================================”
Write-Host “.SYNOPSIS”
Write-Host “Moves a specified number of emails from a source folder to a”
Write-Host “destination folder in Outlook.”
Write-Host “”
Write-Host “.DESCRIPTION”
Write-Host “Usage Instructions:”
Write-Host “1. Ensure Outlook is running with the same privileges as PowerShell.”
Write-Host “2. Select the SOURCE folder when prompted.”
Write-Host “3. Select the DESTINATION folder when prompted.”
Write-Host “4. Enter the specific number of emails to move (Enter 0 for ALL).”
Write-Host “================================================================`n”
# Create a COM object to interact with the Outlook application.
$outlook = New-Object -ComObject Outlook.Application
# Access the Messaging Application Programming Interface (MAPI) namespace,
# which is required to access Outlook folders and items.
$namespace = $outlook.GetNameSpace(“MAPI”)
# ——————————————————————-
# 2. FOLDER SELECTION
# ——————————————————————-
# Prompt the user with a dialogue box to select the source folder.
Write-Host “Select the SOURCE folder…”
$source = $namespace.PickFolder()
# Exit the script if the user clicks ‘Cancel’ or closes the prompt.
if ($null -eq $source) { exit }
# Prompt the user with a dialogue box to select the destination folder.
Write-Host “Select the DESTINATION folder…”
$destination = $namespace.PickFolder()
# Exit the script if no destination is selected, or if the source and
# destination folders are exactly the same (preventing an infinite loop).
if ($null -eq $destination -or $source.EntryID -eq $destination.EntryID) { exit }
# ——————————————————————-
# 3. ITEM INVENTORY
# ——————————————————————-
# Retrieve all items (emails, meetings, etc.) within the selected source folder.
$items = $source.Items
# Count the total number of items present.
$itemCount = $items.Count
Write-Host “`nFound $itemCount item(s) in $($source.Name).”
# If the folder is empty, terminate the script as there is nothing to do.
if ($itemCount -eq 0) {
Write-Host “No items to move.”
exit
}
# ——————————————————————-
# 4. USER INPUT & VALIDATION
# ——————————————————————-
# Initialise the limit variable.
[int]$limit = -1
# Create an infinite loop that only breaks when valid input is provided.
while ($true) {
$userInput = Read-Host “How many emails would you like to move? (Enter 0 for ALL)”
# Attempt to parse the input as an integer. It must be a number and 0 or greater.
if ([int]::TryParse($userInput, [ref]$limit) -and $limit -ge 0) {
break # Exit the loop if valid.
}
Write-Host “Please enter a valid number (0 or greater).”
}
# If the user enters 0 (meaning ‘all’), or asks to move more items than
# actually exist, cap the limit at the total number of available items.
if ($limit -eq 0 -or $limit -gt $itemCount) {
$limit = $itemCount
Write-Host “Setting limit to $itemCount (all available items).”
}
# ——————————————————————-
# 5. EXECUTION & MOVEMENT
# ——————————————————————-
# Calculate the index at which the loop should stop to move exactly
# the requested amount of items.
$stopAt = $itemCount – $limit + 1
$processed = 0
# Loop through the items BACKWARDS. This is critical when modifying COM collections;
# moving item #1 shifts item #2 to position #1, breaking a standard forward loop.
for ($i = $itemCount; $i -ge $stopAt; $i–) {
$processed++
# Update the visual progress bar in the PowerShell console.
Write-Progress -Activity “Moving Emails” -Status “Processed $processed of $limit” -PercentComplete (($processed / $limit) * 100)
# Execute the move command. Casting to [void] prevents the COM object
# from outputting enumeration data to the pipeline, which can cause failures.
[void]$items.Item($i).Move($destination)
}
# Clear the progress bar from the screen once finished.
Write-Progress -Activity “Moving Emails” -Completed
# Display the final summary.
Write-Host “`nCompleted. Moved $limit email(s).”