diff --git a/M365/MDO/ResendFailedMail.ps1 b/M365/MDO/ResendFailedMail.ps1 new file mode 100644 index 000000000..f3966ccae --- /dev/null +++ b/M365/MDO/ResendFailedMail.ps1 @@ -0,0 +1,319 @@ +# Copyright (c) Microsoft Corporation. +# Licensed under the MIT License. + +# Get-MgContext +#Requires -Modules Microsoft.Graph.Authentication +# Get-MgUserMessage +#Requires -Modules Microsoft.Graph.Mail +# Get-EXOMailbox Get-ConnectionInformation Get-MessageTrace +#Requires -Modules ExchangeOnlineManagement -Version 3.0.0 + +# How to connect: +# $ClientSecretCredential = Get-Credential -Credential "[YOUR APP ID HERE]" +# Connect-MgGraph -TenantId ""[YOUR TENANT ID HERE]"" -ClientSecretCredential $ClientSecretCredential -NoWelcome + +<# +.SYNOPSIS +Re-sends email in Failed state from Exchange Online to the originally intended recipients with parameters to target the emails to resend. + +.DESCRIPTION +This script re-sends all Failed email from the past day, by default, or allows you to use the following parameters to target which emails to resend. + +.PARAMETER SenderAddress + Filter emails based on the sender's address. +.PARAMETER RecipientAddress + Filter emails based on the recipient's address. +.PARAMETER Subject + Filter emails based on the email Subject. +.PARAMETER MessageID + Filter emails based on the MessageId address. You must put the MessageId in double quotes. +.PARAMETER Days + Resend emails that failed within the past X number of days. Default is 1 day. +.PARAMETER Force + Sends emails without confirmation prompt. +.PARAMETER IncludeDuplicates + Will resend all emails with the same Message Id. +.PARAMETER SkipConnectionCheck + Skips connection check for Graph and Exchange Online. +.PARAMETER SkipVersionCheck + Skips the version check of the script. +.PARAMETER ScriptUpdateOnly + Just updates script version to latest one. + +.EXAMPLE + .\ResendFailedMail.ps1 + To resend all Failed email from the past day. + +.EXAMPLE + .\ResendFailedMail.ps1 -SenderAddress gary@contoso.com -RecipientAddress ahmad@fabrikam.com -Days 7 + To resend Failed email from specific sender, recipient, and specified number of days. + +.EXAMPLE + .\ResendFailedMail.ps1 -Force -SenderAddress gary@contsoso.com -Days 5 + To resend Failed email from a specific sender for the past 5 days without a confirmation prompt. +#> + +[CmdletBinding(DefaultParameterSetName = 'ResendCopyFailed', SupportsShouldProcess = $true, ConfirmImpact = 'High')] +param( + [Parameter(Mandatory = $false, ParameterSetName = "ResendCopyFailed")] + [Parameter(Mandatory = $false, ParameterSetName = "ResendCopyFailedDays")] + [string[]]$SenderAddress, + [Parameter(Mandatory = $false, ParameterSetName = "ResendCopyFailed")] + [Parameter(Mandatory = $false, ParameterSetName = "ResendCopyFailedDays")] + [string[]]$Subject, + [Parameter(Mandatory = $false, ParameterSetName = "ResendCopyFailed")] + [Parameter(Mandatory = $false, ParameterSetName = "ResendCopyFailedDays")] + [string[]]$RecipientAddress , + [Parameter(Mandatory = $false, ParameterSetName = "ResendCopyFailed")] + [Parameter(Mandatory = $false, ParameterSetName = "ResendCopyFailedDays")] + [string[]]$MessageId, + [Parameter(Mandatory = $false, ParameterSetName = "ResendCopyFailed")] + [Parameter(Mandatory = $false, ParameterSetName = "ResendCopyFailedDays")] + [switch]$IncludeDuplicates, + [Parameter(Mandatory = $false, ParameterSetName = "ResendCopyFailed")] + [Parameter(Mandatory = $false, ParameterSetName = "ResendCopyFailedDays")] + [switch]$Force, + [Parameter(Mandatory = $false, ParameterSetName = "ResendCopyFailed")] + [DateTime]$StartDate, + [Parameter(Mandatory = $false, ParameterSetName = "ResendCopyFailed")] + [DateTime]$EndDate, + [Parameter(Mandatory = $false, ParameterSetName = "ResendCopyFailedDays")] + [ValidateRange(1, 10)] + [Int16]$Days, + [Parameter(Mandatory = $false, ParameterSetName = "ResendCopyFailed")] + [Parameter(Mandatory = $false, ParameterSetName = "ResendCopyFailedDays")] + [switch]$SkipConnectionCheck, + [Parameter(Mandatory = $false, ParameterSetName = "ResendCopyFailed")] + [Parameter(Mandatory = $false, ParameterSetName = "ResendCopyFailedDays")] + [switch]$SkipVersionCheck, + [Parameter(Mandatory = $true, ParameterSetName = "ScriptUpdateOnly")] + [switch]$ScriptUpdateOnly +) + +$Script:DualLoggingEnabled = $true +. $PSScriptRoot\..\..\Shared\GenericScriptStartLogging.ps1 + +$versionsUrl = "https://aka.ms/ResendFailedMail-VersionsURL" +. $PSScriptRoot\..\..\Shared\ScriptUpdateFunctions\GenericScriptUpdate.ps1 + +$recipientCache = @{} + +Write-Verbose "Url to check for new versions of the script is: $versionsUrl" + +function Test-GraphContext { + [OutputType([bool])] + param ( + [Parameter(Mandatory = $true)] + [string[]]$Scopes, + [Parameter(Mandatory = $true)] + [string[]]$ExpectedScopes + ) + + $validScope = $true + foreach ($expectedScope in $ExpectedScopes) { + if ($Scopes -contains $expectedScope) { + Write-Verbose "Scopes $expectedScope is present." + } else { + Write-Host "The following scope is missing: $expectedScope" -ForegroundColor Red + $validScope = $false + } + } + return $validScope +} + +if (-not $SkipConnectionCheck) { + #Validate EXO PS Connection + $exoConnection = $null + try { + $exoConnection = Get-ConnectionInformation -ErrorAction Stop + } catch { + Write-Host "Error checking EXO connection:`n$_" -ForegroundColor Red + Write-Host "Verify that you have ExchangeOnlineManagement module installed." -ForegroundColor Yellow + Write-Host "You need a connection to Exchange Online; you can use:" -ForegroundColor Yellow + Write-Host "Connect-ExchangeOnline" -ForegroundColor Yellow + Write-Host "Exchange Online Powershell Module is required." -ForegroundColor Red + Write-Verbose "$_" + exit + } + if ($null -eq $exoConnection) { + Write-Host "Not connected to EXO" -ForegroundColor Red + Write-Host "You need a connection to Exchange Online; you can use:" -ForegroundColor Yellow + Write-Host "Connect-ExchangeOnline" -ForegroundColor Yellow + Write-Host "Exchange Online Powershell Module is required." -ForegroundColor Red + exit + } elseif ($exoConnection.count -eq 1) { + Write-Host " " + Write-Host "Connected to EXO" + Write-Host "Session details" + Write-Host "Tenant Id: $($exoConnection.TenantId)" + Write-Host "User: $($exoConnection.UserPrincipalName)" + } else { + Write-Host "You have more than one EXO session. Please use just one session." -ForegroundColor Red + exit + } + + #Validate Graph is connected + $graphConnection = $null + Write-Host " " + try { + $graphConnection = Get-MgContext -ErrorAction Stop + } catch { + Write-Host "Error checking Graph connection:`n$_" -ForegroundColor Red + Write-Host "Verify that you have Microsoft.Graph.Mail and Microsoft.Graph.Users.Actions modules installed and loaded." -ForegroundColor Yellow + Write-Host "You could use:" -ForegroundColor Yellow + Write-Host "`t`$ClientSecretCredential = Get-Credential -Credential ""[YOUR APP ID HERE]""" -ForegroundColor Yellow + Write-Host "`t# Enter client_secret in the password prompt." -ForegroundColor Yellow + Write-Host "`tConnect-MgGraph -TenantId ""[YOUR TENANT ID HERE]"" -ClientSecretCredential `$ClientSecretCredential -NoWelcome" -ForegroundColor Yellow + Write-Verbose "$_" + exit + } + if ($null -eq $graphConnection) { + Write-Host "Not connected to Graph" -ForegroundColor Red + Write-Host "Verify that you have Microsoft.Graph.Mail and Microsoft.Graph.Users.Actions modules installed and loaded." -ForegroundColor Yellow + Write-Host "You could use:" -ForegroundColor Yellow + Write-Host "`t`$ClientSecretCredential = Get-Credential -Credential ""[YOUR APP ID HERE]""" -ForegroundColor Yellow + Write-Host "`t# Enter client_secret in the password prompt." -ForegroundColor Yellow + Write-Host "`tConnect-MgGraph -TenantId ""[YOUR TENANT ID HERE]"" -ClientSecretCredential `$ClientSecretCredential -NoWelcome" -ForegroundColor Yellow + exit + } elseif ($graphConnection.count -eq 1) { + $expectedScopes = 'Mail.Read', 'Mail.Send' + if (Test-GraphContext -Scopes $graphConnection.Scopes -ExpectedScopes $expectedScopes) { + Write-Host "Connected to Graph" + Write-Host "Session details" + Write-Host "TenantID: $(($graphConnection).TenantId)" + Write-Host "AuthType: $(($graphConnection).AuthType)" + } else { + Write-Host "We cannot continue without Graph Powershell session without Expected Scopes." -ForegroundColor Red + Write-Host "Verify that you have Microsoft.Graph.Mail and Microsoft.Graph.Users.Actions modules installed and loaded." -ForegroundColor Yellow + Write-Host "You could use:" -ForegroundColor Yellow + Write-Host "`t`$ClientSecretCredential = Get-Credential -Credential ""[YOUR APP ID HERE]""" -ForegroundColor Yellow + Write-Host "`t# Enter client_secret in the password prompt." -ForegroundColor Yellow + Write-Host "`tConnect-MgGraph -TenantId ""[YOUR TENANT ID HERE]"" -ClientSecretCredential `$ClientSecretCredential -NoWelcome" -ForegroundColor Yellow + exit + } + } else { + Write-Host "You have more than one Graph sessions. Please use just one session." -ForegroundColor Red + exit + } + if (($graphConnection.TenantId) -ne ($exoConnection.TenantId) ) { + Write-Host "`nThe Tenant Id from Graph and EXO are different. Please use the same tenant." -ForegroundColor Red + exit + } +} + +if ($PsCmdlet.ParameterSetName -eq 'ResendCopyFailedDays') { + $StartDate = (Get-Date).AddDays(-$Days) + Write-Verbose "StartDate: $StartDate" + $EndDate = Get-Date + Write-Verbose "EndDate: $EndDate" +} + +$traceParams = @{ + Status = "Failed" +} + +if ($StartDate) { $traceParams["StartDate"] = $StartDate } +if ($EndDate) { $traceParams["EndDate"] = $EndDate } +if ($RecipientAddress ) { $traceParams["RecipientAddress"] = $RecipientAddress } +if ($SenderAddress) { $traceParams["SenderAddress"] = $SenderAddress } +if ($MessageId) { $traceParams["MessageId"] = $MessageId } + +try { + [array]$failedMessages = Get-MessageTrace @traceParams -ErrorAction Stop +} catch { + Write-Host "Error: $_.Exception.Message" -ForegroundColor Red + exit +} + +if ($failedMessages.count -ge 1000) { + Write-Host "We get more than 1000 messages, please limit your search." -ForegroundColor Red + exit +} + +if (-not $IncludeDuplicates) { + [array]$failedMessages = $failedMessages | Sort-Object MessageId -Unique +} + +$verifiedAcceptedSenderMessages = New-Object System.Collections.Generic.List[object] +$count = 0 +$totalMessages = $failedMessages.Count +foreach ($failedMessage in $failedMessages) { + $count++ + Write-Progress -Activity "Checking Progress" -Status "$count of $totalMessages" -PercentComplete ($count / $totalMessages * 100) -CurrentOperation "Checking message $($failedMessage.MessageId) - Subject: $($failedMessage.Subject)" + Write-Verbose "Checking $($failedMessage.SenderAddress)" + $tempAddress = $null + if ($recipientCache.ContainsKey($failedMessage.SenderAddress)) { + Write-Verbose "RecipientAddress $($failedMessage.SenderAddress) found in cache" + if ($recipientCache[$failedMessage.SenderAddress]) { + $verifiedAcceptedSenderMessages.Add($failedMessage) + } else { + Write-Verbose "Sender $($failedMessage.SenderAddress) is not a recipient in this tenant." + Write-Verbose "Discarded $($failedMessage.MessageId) - Subject: $($failedMessage.Subject)" + } + } else { + try { + $tempAddress = Get-EXOMailbox $failedMessage.SenderAddress -ErrorAction Stop + if ($null -eq $tempAddress) { + Write-Verbose "Sender $($failedMessage.SenderAddress) is not a recipient in this tenant." + Write-Verbose "Discarded $($failedMessage.MessageId) - Subject: $($failedMessage.Subject)" + $recipientCache[$failedMessage.SenderAddress] = $false + } else { + Write-Verbose "Added to cache Recipient $($failedMessage.SenderAddress) with Id $($failedMessage.SenderAddress)" + $recipientCache[$failedMessage.SenderAddress] = $true + Write-Verbose "Verified $($failedMessage.SenderAddress)" + $verifiedAcceptedSenderMessages.Add($failedMessage) + } + } catch { + Write-Verbose "Error getting Sender Address $($failedMessage.SenderAddress)" + Write-Verbose "Discarded $($failedMessage.MessageId) - Subject: $($failedMessage.Subject)" + $recipientCache[$failedMessage.SenderAddress] = $false + Write-Verbose "$_" + } + } +} + +$totalMessages = $verifiedAcceptedSenderMessages.Count +if ($totalMessages -gt 0) { + if (-not $Force) { + Write-Host "`nWe are going to resend the following messages:" + Write-Host ($verifiedAcceptedSenderMessages | Format-Table -AutoSize Received, MessageId, SenderAddress, RecipientAddress, Subject | Out-String) + Write-Host "Total number of messages: $totalMessages`n" + } + + if ($Force -or $PSCmdlet.ShouldContinue("Are you sure you want to do it?", "Resend messages")) { + $count = 0 + $resendCount = 0 + foreach ( $failedMessage in $verifiedAcceptedSenderMessages ) { + $count++ + Write-Progress -Activity "Resending Progress" -Status "$count of $totalMessages" -PercentComplete ($count / $totalMessages * 100) -CurrentOperation "Resending message $($failedMessage.MessageId) - Subject: $($failedMessage.Subject)" + try { + $fullMessage = $null + $fullMessage = Get-MgUserMessage -UserId $failedMessage.SenderAddress -Filter "InternetMessageId eq '$($failedMessage.MessageId)'" -ExpandProperty Attachments -ErrorAction Stop | Sort-Object ReceivedDateTime | Select-Object -First 1 + } catch { + Write-Host "Error getting message $($failedMessage.MessageId) - Subject: $($failedMessage.Subject)" -ForegroundColor Red + Write-Verbose "$_" + continue + } + if ($fullMessage.Count -eq 0) { + Write-Host "Message not found for $($failedMessage.MessageId)" -ForegroundColor Yellow + } else { + Write-Verbose "Resending message $($failedMessage.MessageId) - Subject: $($fullMessage.Subject)" + try { + Send-MgUserMessage -UserId $failedMessage.SenderAddress -MessageId $fullMessage.Id + Write-Host "Resent Message: $($failedMessage.MessageId) - Subject: $($fullMessage.Subject)" + $resendCount++ + } catch { + Write-Host "Error resending message $($failedMessage.MessageId) - Subject: $($fullMessage.Subject)" -ForegroundColor Red + Write-Verbose "$_" + } + } + } + Write-Host "Summary" + Write-Host "Total Successful Resent: $resendCount" + if ($totalMessages - $resendCount -gt 0) { + Write-Host "Total Unsuccessful Resent: $($totalMessages-$resendCount)" -ForegroundColor Yellow + } + } +} else { + Write-Host "No messages found" -ForegroundColor Yellow +} diff --git a/docs/M365/MDO/ResendFailedMail.md b/docs/M365/MDO/ResendFailedMail.md new file mode 100644 index 000000000..3f9e665e5 --- /dev/null +++ b/docs/M365/MDO/ResendFailedMail.md @@ -0,0 +1,134 @@ +# ResendFailedMail + +Download the latest release: [ResendFailedMail.ps1](https://github.com/microsoft/CSS-Exchange/releases/latest/download/ResendFailedMail.ps1) + +Use this script to identify and resend failed emails from Exchange Online. It leverages the Microsoft Exchange Online and Graph Powershell modules to retrieve message IDs, message bodies, and attachments, and resend them using PowerShell. It provides filtering options like sender, recipient, subject, start and end dates, and message ID so you can target only the failed emails you want to resend. + +The script can help in this type of scenario: + +- Your entire tenant has been blocked due to exceeding sending threshold limits, and you have legitimate email that still needs to go out. + +- A user has exceeded the sending limits for Exchange Online, for example, and becomes blocked from sending. + +- After the problem is mitigated and the sender or tenant is unblocked, you need to resend some legitimate outbound or internal emails. + +- Exchange Online will not do this automatically nor has any tools to do it that do not require scripting. This script will help you do that easily. + +!!! note + The script can only be used to send email that is currently in a mailbox to the originally intended recipients, and it cannot be used to redirect email to a different recipient. + +## Prerequisites +Before running this script, ensure you meet the following prerequisites: + +1. The Exchange Online Powershell module must be installed to retrieve the failed message IDs. + +2. The `Microsoft.Graph.Authentication`, `Microsoft.Graph.Mail`, and `Microsoft.Graph.Users.Actions` modules must be installed to read and send emails. + + - Here's how you can install the required modules/submodules: + +```powershell +Install-Module -Name ExchangeOnlineManagement +Install-Module -Name Microsoft.Graph.Authentication +Install-Module -Name Microsoft.Graph.Users.Actions +Install-Module -Name Microsoft.Graph.Mail +``` + +3. An App must be registered in Azure Active Directory to interact with the Microsoft Graph API specifically to run this script. + + - You can register a Microsoft Azure app in your tenant here:
https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade + - Click **New registration**. + - Provide a name and account type. + - **Redirect URI** can be left blank. + + - Assign permissions: + - Under **Manage | API permissions** for the app, click **Add a permission**. + - Select **Microsoft Graph**. + - Select the **Application permission** type. + - Search for and select the following permissions: + - **Mail.Read** (Application) + - **Mail.Send** (Application) + - Grant admin consent for your tenant for both the permissions. + - When created, the API permissions should look like this: + !['No Logical inconsistencies found'](img/API-perms.png) + + - Create a new client secret for the app under `Manage | Certificates & secrets`. + + !!! warning + Save the Value field of the secret **immediately** after creating it; you can't retrieve it later. + + !!! tip + Customize the duration of the secret to expire soon if you don't expect to use the app for an extended period. + + - Use the `client_id`, `tenant_id`, and `client_secret` obtained during app registration to authenticate with Microsoft Graph in the script (connection instructions below). +
+4. After completion of the above steps, and before running the script, connect to Exchange Online and Graph API with Powershell, as follows: + +```powershell +Connect-ExchangeOnline -ShowBanner:$false + +$ClientSecretCredential = Get-Credential -Credential "[YOUR APP ID HERE]" +# Enter client_secret in the password prompt. +Connect-MgGraph -TenantId "[YOUR TENANT ID HERE]" -ClientSecretCredential $ClientSecretCredential -NoWelcome +``` + +You can find the Microsoft Graph modules in the following link: +    https://www.powershellgallery.com/packages/Microsoft.Graph/ +    https://learn.microsoft.com/en-us/powershell/microsoftgraph/installation?view=graph-powershell-1.0#installation + +You can find the Exchange module and information in the following links: +    https://learn.microsoft.com/en-us/powershell/exchange/exchange-online-powershell-v2?view=exchange-ps +    https://www.powershellgallery.com/packages/ExchangeOnlineManagement + +## Parameters and Use Cases: +Run the script with the Days parameter to specify the number of days in the past to retrieve email with a **Failed** status as well as with the Sender parameter. You will be prompted before executing this command. + +!!! warning + + Make sure the original cause of the failed sending is fixed, or the script will also fail to send it. + +!['No Logical inconsistencies found'](img/ResendFailedMail-4Days+Sender.png) + +**Script Output 1: Resending Last 4 Days of Failed Email from Specific Sender** + +Run the script with no parameters to resend all Failed email from the past day. + +!['No Logical inconsistencies found'](img/ResendFailedMail-No_Params.png) + +**Script Output 2: Default Execution of Script with No Parameters** + + +## Additional examples + +To resend email from specific sender, recipient, and number of days, run the following: +```powershell +.\ResendFailedMail.ps1 -Sender gary@contoso.com -Recipient ahmad@fabrikam.com -Days 7 +``` +
To resend email from a specific sender for the past 5 days without a confirmation prompt, run the following: +```powershell +.\ResendFailedMail.ps1 -Force -Sender gary@contsoso.com -Days 5 +``` +
To resend email between a specific start and end date, run the following: +```powershell +.\ResendFailedMail.ps1 -StartDate 12-Oct-2024 -EndDate 14-Oct-2024 +``` +
To resend an email based on the Message ID, and include any duplicates, run the following: +```powershell +.\ResendFailedMail.ps1 -MessageId "<1111XXX@MailServer.contoso.com>" -IncludeDuplicates +``` + +## Parameters - all parameters are optional + +Parameter | Description | +----------|-------------| +SenderAddress | Filter emails based on the sender's address. +RecipientAddress | Filter emails based on the recipient's address. +Subject | Filter emails based on the email Subject. +MessageId | Filter emails based on the MessageId address. **You must put the MessageId in double quotes** +StartDate | Specify the start date of the inclusion period of emails to resend. The maximum is 10 days prior to the current date. +EndDate | Specify the end date of the inclusion period of emails to resend. +Days | Resend emails that failed within the past X number of days. Default is 1 day. The maximum is 10 days. +Force | Sends emails without confirmation prompt. +IncludeDuplicates | Will resend all emails with the same Message Id. +SkipConnectionCheck | Skips connection check for Graph and Exchange Online. +SkipVersionCheck | Skips the version check of the script. +ScriptUpdateOnly | Just updates script version to latest one. diff --git a/docs/M365/MDO/img/API-perms.png b/docs/M365/MDO/img/API-perms.png new file mode 100644 index 000000000..7edd3a5b2 Binary files /dev/null and b/docs/M365/MDO/img/API-perms.png differ diff --git a/docs/M365/MDO/img/ResendFailedMail-4Days+Sender.png b/docs/M365/MDO/img/ResendFailedMail-4Days+Sender.png new file mode 100644 index 000000000..ae24ce65f Binary files /dev/null and b/docs/M365/MDO/img/ResendFailedMail-4Days+Sender.png differ diff --git a/docs/M365/MDO/img/ResendFailedMail-No_Params.png b/docs/M365/MDO/img/ResendFailedMail-No_Params.png new file mode 100644 index 000000000..cf1906d22 Binary files /dev/null and b/docs/M365/MDO/img/ResendFailedMail-No_Params.png differ diff --git a/mkdocs.yml b/mkdocs.yml index 8dbf71e05..e3ba7e579 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -80,6 +80,7 @@ nav: - M365: - MDO: - MDOThreatPolicyChecker: M365/MDO/MDOThreatPolicyChecker.md + - ResendFailedMail: M365/MDO/ResendFailedMail.md - DLT365Groupsupgrade: M365/DLT365Groupsupgrade.md - Get-LargeMailboxFolderStatistics: M365/Get-LargeMailboxFolderStatistics.md - Performance: