Send-RjReportEmail

Gebrandete HTML-Berichtsmails aus Azure Automation-Runbooks über Microsoft Graph mithilfe von Markdown-Inhalten senden.

Überblick

Send-RjReportEmail ist der Standard-Helfer für das Versenden von Berichten per E-Mail aus RealmJoin-Reporting-Runbooks. Er nimmt Markdown-Inhalt entgegen, wandelt ihn in eine RealmJoin-gebrandete responsive HTML-E-Mail um, fügt optionale Dateien und eingebettete Branding-Grafiken (Kopf-/Fußzeile) hinzu und sendet das Ergebnis über Microsoft Graph sendMail Endpunkt.

Wesentliche Merkmale:

• Markdown rein, HTML raus — Runbooks verfassen den Berichtstext in Markdown; die Funktion rendert ihn zu HTML im passenden Design, das in Outlook Classic, New Outlook, Outlook Web, mobilen Clients und im Dunkelmodus funktioniert.

• Eine E-Mail pro Empfänger — wenn mehrere Empfänger angegeben werden, sendet die Funktion an jede Adresse eine separate Nachricht statt einer einzigen Mail an mehrere Empfänger. Das ist ein datenschutzorientiertes Design mit standardmäßigem BCC.

• Eingebettete gebrandete Kopf- und Fußzeile — mitgelieferte PNG-Assets werden als CID-Anhänge gesendet und vom eingebetteten HTML referenziert. Beide können vollständig überschrieben oder unterdrückt werden.

• Selbstverbindend — wenn keine Graph-Sitzung aktiv ist, ruft die Funktion transparent Connect-RjRbGraph (oder Connect-MgGraph -Identity wenn -UseNativeGraphRequest gesetzt ist).

• Robust — fehlgeschlagene Lesevorgänge von Anhängen, fehlende Bildüberschreibungen oder sendMail-Fehler pro Empfänger werden gemeldet, brechen den gesamten Batch jedoch nicht ab, es sei denn alle Empfänger schlagen fehl.

Zentral verwaltete E-Mail-Einstellungen (Absenderadresse, Service-Desk-Informationen) sind in Runbook Report Settings — dieses Dokument konzentriert sich auf den Aufruf der Funktion aus einem Runbook heraus.

Voraussetzungen

Absenderpostfach

Ein lizenziertes Microsoft 365-Postfach (typischerweise ein dediziertes freigegebenes Postfach wie [email protected]) ist als die Von Adresse erforderlich. Der verwalteten Identität des Automation Account muss erlaubt sein, im Namen dieses Postfachs über Microsoft Graph zu senden, mittels der Mail.Send Anwendungsberechtigung (über RBAC for Applications begrenzt, wenn Sie die Identität auf ein einzelnes Postfach beschränken möchten).

Graph-Berechtigungen

Szenario	Erforderliche Berechtigung
Standard (Invoke-RjRbRestMethodGraph)	Mail.Send (Application) auf dem Absenderpostfach
Mit -UseNativeGraphRequest	Dasselbe — der Aufruf geht weiterhin an /users/{id}/sendMail

Modulverbindung

Standardmäßig verwendet die Funktion Invoke-RjRbRestMethodGraph aus diesem Modul. Wenn keine Verbindung aktiv ist, verbindet sie sich automatisch über Connect-RjRbGraph. Wenn -UseNativeGraphRequest gesetzt ist, prüft die Funktion stattdessen Get-MgContext und ruft Connect-MgGraph -Identity -NoWelcome bei Bedarf auf.

Schnellstart

Der minimale Aufruf benötigt nur den Absender, den Empfänger, einen Betreff und den Markdown-Text:

Send-RjReportEmail `
    -EmailFrom "[email protected]" `
    -EmailTo   "[email protected]" `
    -Subject   "Wöchentlicher Bericht" `
    -MarkdownContent @"
# Wöchentlicher Bericht

Hallo Alice,

hier sind die Zahlen dieser Woche:

- Neue Geräte angemeldet: **42**
- Lizenzkonformität: **98%**
"@

Dies erzeugt eine vollständig gebrandete RealmJoin-E-Mail mit der Standard-Kopf- und Fußzeile, Unterstützung für Hell-/Dunkelmodus und dem Tenant-/Versionsblock in der Fußzeile.

Parameter

Erforderlich

Parameter	Typ	Beschreibung
EmailFrom	Zeichenfolge	UPN oder Objekt-ID des Absenderpostfachs. Wird verwendet als /users/{id}/sendMail.
EmailTo	Zeichenfolge	Empfängeradresse. Einzelner String — mehrere Adressen werden als kommagetrennte Liste übergeben, siehe unten.
Betreff	Zeichenfolge	Betreffzeile. Wird auch in das HTML eingefügt <title> Element.
MarkdownContent	Zeichenfolge	Berichtstext in Markdown. Siehe Markdown-Unterstützung für die unterstützte Syntax.

Optional — Inhalt

Parameter	Typ	Standard	Beschreibung
Anhänge	String[]	@()	Lokale Dateipfade zum Anhängen. Fehlende Dateien werden protokolliert und übersprungen, nicht lesbare Dateien lösen eine Warnung aus, brechen den Versand jedoch nicht ab. Der MIME-Typ wird aus der Dateiendung abgeleitet.
saveToSentItems	bool	$true	Wenn $true die gesendete Nachricht im Gesendete Elemente. Auf $false für Berichte mit hohem Volumen, um das Postfach nicht zu füllen.
TenantDisplayName	Zeichenfolge	—	Wird in der Tenant-Info-Box angezeigt, die am Ende des Inhaltsbereichs eingebettet ist.
ReportVersion	Zeichenfolge	—	Wird in der Tenant-Info-Box angezeigt (verwenden Sie semantische Versionszeichenfolgen, Build-Nummern oder einen Runbook-Namen + Datum).

Optional — Branding

Parameter	Typ	Standard	Beschreibung
HeaderImage	Zeichenfolge	mitgeliefert Assets/Header.png	Lokaler Dateipfad zu einer PNG/JPG/GIF-Datei, die die Standard-Kopfgrafik überschreibt. Das Runbook muss jede URL/jedes Blob im Vorfeld in eine lokale Datei auflösen (z. B. über Get-AzStorageBlobContent). Fehlende/nicht lesbare Überschreibungen fallen auf den mitgelieferten Standard zurück und erzeugen eine Warnung.
FooterImage	Zeichenfolge	mitgeliefert Assets/Footer.png	Gleiche Behandlung wie HeaderImage. Die Fußzeile wird als einzelnes anklickbares Bild gerendert — jeder Branding-Text, jedes Logo oder jede URL muss in das PNG eingebettet sein.
FooterLink	Zeichenfolge	https://www.realmjoin.com	URL, die als href und title des Links verwendet wird, der das Fußzeilenbild umschließt.
NoHeader	Schalter	aus	Unterdrückt die Kopfgrafik vollständig. Wenn kombiniert mit HeaderImage, wird eine Warnung ausgegeben und die Überschreibung ignoriert.
NoFooter	Schalter	aus	Unterdrückt die Fußgrafik und ihren Link vollständig. Wenn kombiniert mit FooterImage oder einer benutzerdefinierten FooterLink, wird eine Warnung ausgegeben und diese Werte werden ignoriert.

Empfohlene Bildabmessungen: 750 × 200 px PNG. Dies entspricht der Breite des E-Mail-Containers und den mitgelieferten Standardwerten. Deutlich andere Seitenverhältnisse können auf schmalen Ansichten verzerrt wirken. Jede Grafik sollte deutlich unter 3 MB bleiben — Graph begrenzt die Gesamt- sendMail anforderung auf 4 MB, und es wird eine Warnung ausgegeben, wenn eines der Bilder 3 MB überschreitet.

Optional — Transport

Parameter	Typ	Standard	Beschreibung
UseNativeGraphRequest	Schalter	aus	Sendet über Invoke-MgGraphRequest (erfordert Microsoft.Graph Modul und eine Connect-MgGraph -Sitzung) statt Invoke-RjRbRestMethodGraph. Verwenden Sie dies, wenn das Runbook auf dem nativen SDK statt auf dem RealmJoin-Wrapper basiert.

Anwendungsbeispiele

Mehrere Empfänger

EmailTo akzeptiert einen einzelnen String mit einer oder mehreren kommagetrennten Adressen. Jede Adresse wird getrimmt, leere Einträge werden entfernt, und für jeden Empfänger wird eine einzelne E-Mail gesendet — die Empfänger sehen einander nicht.

Send-RjReportEmail `
    -EmailFrom "[email protected]" `
    -EmailTo   "[email protected], [email protected], [email protected]" `
    -Subject   "Monatsinventar" `
    -MarkdownContent $reportMd

Mit Anhängen und Tenant-Metadaten

$csvPath = Join-Path $env:TEMP 'devices.csv'
$exportData | Export-Csv -Path $csvPath -NoTypeInformation -Encoding UTF8

Send-RjReportEmail `
    -EmailFrom         "[email protected]" `
    -EmailTo           "[email protected]" `
    -Subject           "Geräteinventur — $(Get-Date -Format 'yyyy-MM-dd')" `
    -MarkdownContent   $reportMd `
    -Attachments       @($csvPath, "$env:TEMP\summary.xlsx") `
    -TenantDisplayName "Contoso Ltd" `
    -ReportVersion     "Geräteinventur v1.4.2"

Die angehängten Dateien werden zusätzlich dazu, dass sie als echte Anhänge zur Nachricht hinzugefügt werden, in einer Box „Angehängte Dateien“ am Ende des E-Mail-Texts aufgeführt.

Benutzerdefiniertes Branding für Kopf- und Fußzeile

Bringen Sie Ihr eigenes Branding ein, indem Sie die Assets zunächst in einen lokalen Pfad herunterladen und dann die resultierenden Pfade übergeben. Die Funktion ruft URLs nicht selbst ab.

# Branding-Assets aus Azure Blob Storage in den temporären Ordner des Runbooks auflösen
$headerPath = Join-Path $env:TEMP 'contoso-header.png'
$footerPath = Join-Path $env:TEMP 'contoso-footer.png'

Get-AzStorageBlobContent -Container 'branding' -Blob 'header.png' -Destination $headerPath -Force | Out-Null
Get-AzStorageBlobContent -Container 'branding' -Blob 'footer.png' -Destination $footerPath -Force | Out-Null

Send-RjReportEmail `
    -EmailFrom        "[email protected]" `
    -EmailTo          "[email protected]" `
    -Subject          "Gebrandeter Bericht" `
    -MarkdownContent  $reportMd `
    -HeaderImage      $headerPath `
    -FooterImage      $footerPath `
    -FooterLink       "https://intranet.contoso.com/it-reports"

Wenn $headerPath fehlt oder nicht lesbar ist, ist der Aufruf dennoch erfolgreich — der mitgelieferte RealmJoin-Standard wird verwendet und eine Warnung protokolliert.

Einfacher Inhalt (ohne Kopf-/Fußzeile)

Für Benachrichtigungen im Alarmstil, die nicht wie eine Marketing-E-Mail aussehen sollen:

Send-RjReportEmail `
    -EmailFrom       "[email protected]" `
    -EmailTo         "[email protected]" `
    -Subject         "[ALARM] Lizenzschwellenwert überschritten" `
    -MarkdownContent "## Lizenzschwellenwert überschritten`n`nWeitere Details im Dashboard." `
    -NoHeader `
    -NoFooter

Verwendung des nativen Microsoft.Graph SDK

Wenn das Runbook bereits über Connect-MgGraph (verwaltete Identität) authentifiziert ist und Sie den RealmJoin-Wrapper nicht mit einbeziehen möchten:

Connect-MgGraph -Identity -NoWelcome

Send-RjReportEmail `
    -EmailFrom             "[email protected]" `
    -EmailTo               "[email protected]" `
    -Subject               "Nativer Graph-Versand" `
    -MarkdownContent       $reportMd `
    -UseNativeGraphRequest

Berichtstext aus einer Datei lesen

Für größere Berichte erzeugen Sie den Markdown-Text in einer .md Datei und lesen Sie ihn ein:

$reportMd = Get-Content -Path .\generated-report.md -Raw

Send-RjReportEmail `
    -EmailFrom       "[email protected]" `
    -EmailTo         "[email protected]" `
    -Subject         "Wöchentlicher Bericht" `
    -MarkdownContent $reportMd

Markdown-Unterstützung

Die Funktion enthält einen integrierten, leichtgewichtigen Markdown→HTML-Konverter. Kein externes Markdown-Modul ist erforderlich. Unterstützte Syntax:

Markdown	Hinweise
# … ###### Überschriften	Alle sechs Ebenen. Leerzeichen nach # ist optional. h1 erhält eine Unterstreichung; der Abstand ist auf Outlook abgestimmt.
**fett**, *kursiv*, ~~durchgestrichen~~	Nur inline (darf sich nicht über mehrere Zeilen erstrecken).
`Inline-Code`	Wird dargestellt als <code> mit hellgrauem Hintergrund.
lang ... abgegrenzte Codeblöcke	Das Sprach-Tag bleibt erhalten als class="language-…". Toleriert außerdem fehlerhafte Einfassungen mit einem einzelnen Backtick.
[Text](url) Links	Öffnet in neuem Tab mit noopener noreferrer.
 Bilder	Eingefügt als <img> (kein Inline-Anhang-Zauber — die URL muss vom E-Mail-Client erreichbar sein).
- Element / 1. Element Listen	Verschachtelte Listen werden durch Einrückung von 2 Leerzeichen pro Ebene unterstützt. Das Mischen von sortierten und unsortierten Listen schließt die vorherige Liste.
Mehrzeilige Listeneinträge	Eine eingerückte, nicht leere Zeile direkt unter einem <li> wird in denselben Eintrag übernommen mit einem <br> weichen Zeilenumbruch — es ist nicht nötig, jeden Eintrag in einer Zeile zu halten.
- [ ] / - [x] Aufgabenlisten	Wird dargestellt als ☐ / ☑ Unicode-Zeichen (grün, wenn markiert). <input type="checkbox"> wird absichtlich vermieden, da Outlook Classic Formularsteuerelemente entfernt. Großes [X] gilt ebenfalls als markiert.
> Zitatblock	Mit farbigem linken Rand und schattiertem Hintergrund dargestellt.
> [!NOTE|TIP|IMPORTANT|WARNING|CAUTION]	GitHub-ähnliche Hinweise. Die erste Zeile des Zitatblocks ist der Marker (allein stehend), die verbleibenden >mit - beginnenden Zeilen bilden den Inhalt. Jeder Typ erhält seine eigene Akzentfarbe, sein eigenes Symbol und seine eigene Titelleiste.
---, ***, ___	Horizontale Linie.
|col|col| Tabellen	Standard-Pipe-Tabellen mit :---, :---:, ---: Ausrichtungsangaben. Kopfzeile + Trennzeichen erforderlich.
\\ Escaping	\*, | usw. werden berücksichtigt, sodass wörtliche Markdown-Zeichen ausgegeben werden können.

Nicht unterstützte Elemente sind Fußnoten, Definitionslisten und HTML-Durchreichung — halten Sie sich bei Markdown an die obige Tabelle.

Verhalten und Fehlerbehandlung

Empfängerparsing

EmailTo wird an Kommas getrennt, jeder Eintrag wird getrimmt, und leere Einträge werden entfernt. Wenn die resultierende Liste leer ist, wirft die Funktion Keine gültigen E-Mail-Empfänger im EmailTo-Parameter gefunden. bevor ein Graph-Aufruf erfolgt.

Fehler pro Empfänger

Jeder Empfänger wird unabhängig versendet. Die Funktion verfolgt Erfolge und Fehler:

• Wenn mindestens ein Versand erfolgreich ist, andere jedoch fehlschlagen, wird eine Warnung mit den fehlgeschlagenen Adressen ausgegeben; die Funktion kehrt normal zurück.

• Wenn alle Versendevorgänge fehlschlagen, wirft die Funktion Fehlgeschlagen, E-Mail an alle Empfänger zu senden: … sodass das Runbook deutlich fehlschlägt.

Fehler bei Anhängen

• Fehlende Dateien (Pfad existiert nicht) — ausführlich protokolliert, still übersprungen.

• Vorhandene, aber nicht lesbare Dateien (gesperrt, Zugriff verweigert) — Warnung ausgegeben, übersprungen, der Rest des Aufrufs wird fortgesetzt.

• Die Box „Angehängte Dateien“ am Ende der E-Mail listet nur Anhänge auf, die erfolgreich gelesen wurden.

Fehler beim Überschreiben von Bildern

Beide HeaderImage und FooterImage fallen bei jedem Fehler (fehlende Datei, nicht unterstützte Erweiterung, IO-Fehler) auf die mitgelieferten Standards zurück. Eine Warnung beschreibt den Fehler und nennt den verwendeten Standard.

Gesamtgrößenlimit

Graph begrenzt sendMail Anfragen insgesamt auf ca. 4 MB (HTML-Text + alle Anhänge, base64-kodiert). Die Funktion gibt eine Warnung aus, wenn eines der Branding-Bilder 3 MB überschreitet. Wenn die Gesamtlast dennoch 4 MB überschreitet, schlägt der Graph-Aufruf selbst fehl; erwägen Sie:

• große Daten stattdessen in den Storage Account-Kanal hochzuladen — siehe Runbook Report Settings.

• Verknüpfen Sie extern gehostete Anhänge, statt sie einzubetten.

• Tabellarische Daten komprimieren (Compress-Archive) vor dem Anhängen.

Integration mit Runbook Report Settings

Reporting-Runbooks ermitteln die Absenderadresse typischerweise aus dem zentralen RealmJoin-Anpassungs-JSON, statt sie fest zu codieren. Die relevanten Einstellungen sind dokumentiert in Runbook Report Settings. Ein typisches Auflösungsschema in einem Runbook sieht so aus:

# Zentralisierte Einstellungen lesen (vom Runbook-Framework aufgelöst)
$emailFrom = (Get-RjRbDefaultValue -Name 'EmailSender' -Section 'RJReport')

if (-not $emailFrom) {
    throw "Kein EmailSender konfiguriert. Siehe https://docs.realmjoin.com/ für Einrichtungsanweisungen."
}

Send-RjReportEmail `
    -EmailFrom       $emailFrom `
    -EmailTo         $RecipientParameter `
    -Subject         $Subject `
    -MarkdownContent $reportMd `
    -TenantDisplayName $TenantDisplayName `
    -ReportVersion     "MyReport v1.0"

Ausgaben

Die Funktion gibt bei Erfolg nichts zurück. Der gesamte Fortschritt wird geschrieben über Write-RjRbLog -Verbose (sichtbar, wenn das Runbook mit -Verbose oder $VerbosePreference = 'Continue'). Warnungen werden zwangsweise über $WarningPreference = 'Continue' geleitet, unabhängig von Überschreibungen auf Aufruferseite, sodass sie zuverlässig im Azure Automation-Jobstream erscheinen.

Siehe auch

• Runbook Report Settings — zentrale Konfiguration des Absenderpostfachs, der Service-Desk-Informationen und des Storage Account-Zustellkanals.

• Microsoft Graph: E-Mail senden — zugrunde liegende API.