Merge pull request #2527 from microsoft/Nickul-AddGetAllMessageTraceScript

Add Get-AllMessageTraceResults script and documentation

Author: dpaulson45

Transport/Get-AllMessageTraceResults.ps1

@@ -0,0 +1,105 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+[CmdletBinding()]
+[Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSUseOutputTypeCorrectly", "")]
+[OutputType([object[]])]
+param(
+    [Parameter(Mandatory)]
+    [DateTime]$StartDate,
+
+    [Parameter(Mandatory)]
+    [DateTime]$EndDate,
+
+    [Parameter()]
+    [string]$FromIP,
+
+    [Parameter()]
+    [string[]]$MessageId,
+
+    [Parameter()]
+    [guid]$MessageTraceId,
+
+    [Parameter()]
+    [string[]]$RecipientAddress,
+
+    [Parameter()]
+    [string[]]$SenderAddress,
+
+    [Parameter()]
+    [ValidateSet("Delivered", "Expanded", "Failed", "FilteredAsSpam", "GettingStatus", "Pending", "Quarantined")]
+    [string[]]$Status,
+
+    [Parameter()]
+    [string]$Subject,
+
+    [Parameter()]
+    [ValidateSet("Contains", "StartsWith", "EndsWith")]
+    [string]$SubjectFilterType,
+
+    [Parameter()]
+    [string]$ToIP,
+
+    [Parameter()]
+    [ValidateRange(1, 5000)]
+    [int]$PageSize = 5000,
+
+    [Parameter()]
+    [ValidateRange(1, 2147483647)]
+    [int]$TimeoutMinutes = 30
+)
+
+$timeout = (Get-Date).AddMinutes($TimeoutMinutes)
+$page = 1
+$allResults = [System.Collections.Generic.List[object]]::new()
+
+# Build splat from bound parameters, excluding our custom ones
+$splatParams = @{}
+$excludeParams = @("TimeoutMinutes", "PageSize", "Verbose", "Debug", "ErrorAction", "WarningAction",
+    "InformationAction", "ErrorVariable", "WarningVariable",
+    "InformationVariable", "OutVariable", "OutBuffer", "PipelineVariable")
+
+foreach ($key in $PSBoundParameters.Keys) {
+    if ($key -notin $excludeParams) {
+        $splatParams[$key] = $PSBoundParameters[$key]
+    }
+}
+
+$splatParams["ResultSize"] = $PageSize
+
+Write-Progress -Activity "Fetching message trace data" -Status "Page $page..."
+$rawResults = @(Get-MessageTraceV2 @splatParams 3>&1)
+$results = @($rawResults | Where-Object { $_ -isnot [System.Management.Automation.WarningRecord] })
+foreach ($w in ($rawResults | Where-Object { $_ -is [System.Management.Automation.WarningRecord] })) {
+    Write-Verbose "Get-MessageTraceV2 warning (page $page): $w"
+}
+if ($results) { $allResults.AddRange($results) }
+
+$timedOut = $false
+while ($results.Count -eq $PageSize) {
+    if ((Get-Date) -ge $timeout) {
+        $timedOut = $true
+        break
+    }
+    $page++
+    $lastResult = $results[-1]
+    $splatParams["StartingRecipientAddress"] = $lastResult.RecipientAddress
+    $splatParams["EndDate"] = $lastResult.Received
+    Write-Progress -Activity "Fetching message trace data" -Status "Retrieved $($allResults.Count) messages (page $page)..."
+    $rawResults = @(Get-MessageTraceV2 @splatParams 3>&1)
+    $results = @($rawResults | Where-Object { $_ -isnot [System.Management.Automation.WarningRecord] })
+    foreach ($w in ($rawResults | Where-Object { $_ -is [System.Management.Automation.WarningRecord] })) {
+        Write-Verbose "Get-MessageTraceV2 warning (page $page): $w"
+    }
+    if ($results) { $allResults.AddRange($results) }
+}
+
+Write-Progress -Activity "Fetching message trace data" -Completed
+
+if ($timedOut) {
+    Write-Warning "Timed out after $TimeoutMinutes minutes with more results available. Returning $($allResults.Count) results collected so far."
+}
+
+Write-Verbose "Total messages retrieved: $($allResults.Count)"
+return $allResults
+

docs/Transport/Get-AllMessageTraceResults.md

@@ -0,0 +1,83 @@
+# Get-AllMessageTraceResults
+
+Download the latest release: [Get-AllMessageTraceResults.ps1](https://github.com/microsoft/CSS-Exchange/releases/latest/download/Get-AllMessageTraceResults.ps1)
+
+This script is a wrapper for the Exchange Online `Get-MessageTraceV2` cmdlet that automatically handles pagination. It requires an active Exchange Online PowerShell session. Results are collected in pages of up to 5000 and fetching continues until all results are returned or a timeout is reached.
+
+## Parameters
+
+-StartDate
+
+The start date of the date range to search. Data is available for the last 90 days, with a maximum of 10 days per query.
+
+-EndDate
+
+The end date of the date range to search.
+
+-SenderAddress
+
+Filters results by the sender's email address. Accepts multiple values separated by commas.
+
+-RecipientAddress
+
+Filters results by the recipient's email address. Accepts multiple values separated by commas.
+
+-MessageId
+
+Filters results by the Message-ID header field of the message.
+
+-MessageTraceId
+
+Filters results by the message trace ID (GUID).
+
+-FromIP
+
+Filters results by the source IP address.
+
+-ToIP
+
+Filters results by the destination IP address.
+
+-Status
+
+Filters results by delivery status. Valid values are: `Delivered`, `Expanded`, `Failed`, `FilteredAsSpam`, `GettingStatus`, `Pending`, `Quarantined`.
+
+-Subject
+
+Filters results by the message subject. Use with `-SubjectFilterType` to control matching behavior.
+
+-SubjectFilterType
+
+Specifies how the `-Subject` value is evaluated. Valid values are: `Contains`, `StartsWith`, `EndsWith`.
+
+-PageSize
+
+The number of results to retrieve per page. Valid range is 1 to 5000. The default value is 5000.
+
+-TimeoutMinutes
+
+The number of minutes before the script stops fetching additional pages. The default value is 30 minutes.
+
+## Examples
+
+Retrieve all messages from the last 7 hours:
+
+```powershell
+$messages = .\Get-AllMessageTraceResults.ps1 -StartDate (Get-Date).AddHours(-7) -EndDate (Get-Date)
+```
+
+Filter by sender and status:
+
+```powershell
+$messages = .\Get-AllMessageTraceResults.ps1 -StartDate (Get-Date).AddHours(-7) -EndDate (Get-Date) -SenderAddress "john@contoso.com" -Status "Delivered"
+```
+
+Filter by recipient with a custom page size:
+
+```powershell
+$messages = .\Get-AllMessageTraceResults.ps1 -StartDate (Get-Date).AddDays(-2) -EndDate (Get-Date) -RecipientAddress "jane@contoso.com" -PageSize 1000
+```
+
+## Output
+
+Returns an array of message trace objects from `Get-MessageTraceV2`. The total number of retrieved messages is displayed upon completion.

mkdocs.yml

@@ -143,6 +143,7 @@ nav:
     - SetupLogReviewer: Setup/SetupLogReviewer.md
   - Transport:
     - Compute-TopExoRecipientsFromMessageTrace: Transport/Compute-TopExoRecipientsFromMessageTrace.md
+    - Get-AllMessageTraceResults: Transport/Get-AllMessageTraceResults.md
     - ReplayQueueDatabases: Transport/ReplayQueueDatabases.md
     - Measure-EmailDelayInMTL: Transport/Measure-EmailDelayInMTL.md
 theme: