Get-MailStoreJobStatus.ps1

<#PSScriptInfo
.VERSION 1.0.0
.GUID b80b9acf-d744-5488-b83f-027632eb421a
.AUTHOR Torsten Weise
.COMPANYNAME powerscripting.de
.COPYRIGHT (c) 2026 Torsten Weise. MIT-Lizenz.
.TAGS Powerscripting German Monitoring Report Windows Backup MailStore PSEdition_Desktop PSEdition_Core
.LICENSEURI https://powerscripting.de/skripte/files/LICENSE.txt
.PROJECTURI https://powerscripting.de/skripte/get-mailstorejobstatus.html
.ICONURI https://powerscripting.de/assets/icon-192.png
.EXTERNALMODULEDEPENDENCIES
.REQUIREDSCRIPTS
.EXTERNALSCRIPTDEPENDENCIES
.RELEASENOTES
Erste Veröffentlichung in der PowerShell Gallery.
.PRIVATEDATA
#>


<#
.SYNOPSIS
    Prüft über die Administration API von MailStore Server, ob die Archivierungsprofile zuletzt erfolgreich gelaufen sind.
 
.DESCRIPTION
    Fragt mit GetWorkerResults alle Läufe von Archivierungsprofilen im gewählten Zeitraum ab und bewertet
    pro Profil den letzten Lauf. Ein Profil gilt als Problem, wenn der letzte Lauf fehlgeschlagen ist,
    mit Fehlern endete oder Elemente nicht archiviert werden konnten. Profile, die mit -ExpectedProfile
    angegeben sind und im Zeitraum gar nicht gelaufen sind, werden ebenfalls gemeldet.
 
    Das Ergebnis erscheint als Tabelle, als HTML-Bericht und auf Wunsch per Mail. Der Exitcode ist
    0 (alles in Ordnung), 1 (Warnung) oder 2 (Fehler), passend für die Aufgabenplanung oder ein RMM-Tool.
 
    Das Skript ist die schlanke Fassung des Pakets "MailStore Job Monitoring". Es nutzt curl.exe, weil
    ältere MailStore-Versionen ein Zertifikat mitbringen, mit dem Invoke-RestMethod unter Windows
    PowerShell 5.1 nicht zurechtkommt.
 
.PARAMETER Server
    Name oder Adresse des MailStore Servers. Standard: localhost.
 
.PARAMETER Port
    Port der Administration API. Standard: 8463.
 
.PARAMETER Credential
    Benutzer mit Administratorrechten in MailStore (z. B. admin). Ohne Angabe wird nachgefragt.
 
.PARAMETER Hours
    Zeitraum in Stunden, der ausgewertet wird. Standard: 24.
 
.PARAMETER ExpectedProfile
    Optional. Namen von Profilen, die im Zeitraum mindestens einmal gelaufen sein müssen.
 
.PARAMETER ReportPath
    Ordner für den HTML-Bericht. Standard: aktueller Ordner.
 
.PARAMETER SmtpServer
    Optional. Mailserver für den Versand des Berichts.
 
.PARAMETER From
    Absender des Berichts.
 
.PARAMETER To
    Empfänger des Berichts.
 
.EXAMPLE
    .\Get-MailStoreJobStatus.ps1 -Credential (Get-Credential admin)
 
    Zeigt den Stand aller Profile der letzten 24 Stunden.
 
.EXAMPLE
    .\Get-MailStoreJobStatus.ps1 -Server archiv01 -Credential $cred -ExpectedProfile 'Exchange Journal' -SmtpServer mail.contoso.local -From mailstore@contoso.local -To it@contoso.local
 
    Meldet zusätzlich, wenn das Journal-Profil in 24 Stunden nicht gelaufen ist, und schickt den Bericht.
 
.NOTES
    Autor: Torsten Weise, powerscripting.de
    Voraussetzung: In der MailStore Server Service Configuration ist die Administration API aktiviert.
    Für den Einsatz als geplante Aufgabe das Kennwort nicht ins Skript schreiben, sondern z. B. mit
    Export-Clixml unter dem Konto der Aufgabe ablegen.
#>

[CmdletBinding()]
param(
    [string] $Server = 'localhost',
    [int] $Port = 8463,
    [pscredential] $Credential = (Get-Credential -Message 'MailStore-Administrator'),
    [ValidateRange(1, 720)] [int] $Hours = 24,
    [string[]] $ExpectedProfile,
    [string] $ReportPath = (Get-Location).Path,
    [string] $SmtpServer,
    [string] $From,
    [string[]] $To
)

function Invoke-MailStoreApi([string] $Method, [string] $Body) {
    $pair = '{0}:{1}' -f $Credential.UserName, $Credential.GetNetworkCredential().Password
    $auth = [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes($pair))
    $url  = "https://${Server}:${Port}/api/invoke/$Method"
    $raw  = curl.exe -k -s -X POST -H "Authorization: Basic $auth" `
        -H 'Content-Type: application/x-www-form-urlencoded' -d $Body $url
    if (-not $raw) { throw "Keine Antwort von $url" }
    ($raw | Out-String).TrimStart([char]0xFEFF).Trim() | ConvertFrom-Json
}

$now  = Get-Date
$body = 'fromIncluding={0}&toExcluding={1}&timeZoneID=$Local' -f
    $now.AddHours(-$Hours).ToString('yyyy-MM-ddTHH:mm:ss'), $now.AddMinutes(1).ToString('yyyy-MM-ddTHH:mm:ss')
$resp = Invoke-MailStoreApi -Method 'GetWorkerResults' -Body $body
if ($resp.statusCode -ne 'succeeded') {
    Write-Error "API-Fehler: $($resp.error.message)"
    exit 2
}

$rows = foreach ($group in (@($resp.result) | Group-Object profileName)) {
    $last   = $group.Group | Sort-Object { [datetime]$_.startTime } -Descending | Select-Object -First 1
    $result = [string]$last.result
    $failed = 0
    if ($last.PSObject.Properties['itemsFailed']) { $failed = [int]$last.itemsFailed }
    $bewertung = if ($result -eq 'failed') { 'Fehler' }
                 elseif ($result -match 'Errors' -or $failed -gt 0) { 'Warnung' }
                 elseif ($result -eq 'cancelled') { 'Warnung' }
                 else { 'OK' }
    [pscustomobject]@{
        Profil       = $group.Name
        Bewertung    = $bewertung
        Ergebnis     = $result
        'Letzter Start' = ([datetime]$last.startTime).ToString('dd.MM.yyyy HH:mm')
        Archiviert   = $last.itemsArchived
        Fehlerhaft   = $failed
        'Läufe'      = $group.Count
    }
}
$rows = @($rows)

foreach ($name in $ExpectedProfile) {
    if ($rows.Profil -notcontains $name) {
        $rows += [pscustomobject]@{ Profil = $name; Bewertung = 'Fehler'; Ergebnis = "kein Lauf in $Hours h"
            'Letzter Start' = ''; Archiviert = ''; Fehlerhaft = ''; 'Läufe' = 0 }
    }
}

if ($rows.Count -eq 0) {
    Write-Host "Keine Läufe in den letzten $Hours Stunden." -ForegroundColor Yellow
    exit 1
}

$errors   = @($rows | Where-Object Bewertung -eq 'Fehler').Count
$warnings = @($rows | Where-Object Bewertung -eq 'Warnung').Count
$status   = if ($errors) { 'FEHLER' } elseif ($warnings) { 'WARNUNG' } else { 'OK' }

$rows | Sort-Object Bewertung, Profil | Format-Table -AutoSize

$title = "[$status] MailStore $Server - $($now.ToString('dd.MM.yyyy HH:mm'))"
$css   = '<style>body{font-family:Segoe UI,Arial,sans-serif;font-size:13px}table{border-collapse:collapse}td,th{border:1px solid #ccc;padding:4px 8px}th{background:#eee}</style>'
$html  = $rows | Sort-Object Bewertung, Profil | ConvertTo-Html -Title $title -Head $css `
    -PreContent "<h2>$title</h2><p>$($rows.Count) Profile, $errors Fehler, $warnings Warnungen.</p>" | Out-String
$file  = Join-Path $ReportPath ("MailStore_{0:yyyy-MM-dd_HHmm}.html" -f $now)
$html | Set-Content -Path $file -Encoding UTF8
Write-Host "Bericht: $file"

if ($SmtpServer -and $From -and $To) {
    Send-MailMessage -SmtpServer $SmtpServer -From $From -To $To -Subject $title -Body $html -BodyAsHtml -Encoding UTF8
}

exit $(if ($errors) { 2 } elseif ($warnings) { 1 } else { 0 })