> For the complete documentation index, see [llms.txt](https://docs.realmjoin.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.realmjoin.com/dev-reference/report-functions/send-rjrbreportemail.md). # Send-RjRbReportEmail ## Overview `Send-RjRbReportEmail` is the standard helper for delivering report emails from RealmJoin reporting runbooks. It takes Markdown content, converts it to a RealmJoin-branded responsive HTML email, attaches optional files and inline branding graphics (header/footer), and sends the result through the Microsoft Graph `sendMail` endpoint. > **Renamed in this release.** The function was renamed from `Send-RjReportEmail` to `Send-RjRbReportEmail` for naming consistency with the rest of the module (`*-RjRb*`). The old name `Send-RjReportEmail` is exported as a backwards-compatible alias, so existing runbooks keep working unchanged — but new runbooks should call `Send-RjRbReportEmail`. Key characteristics: * **Markdown in, HTML out** — runbooks compose the report body in Markdown; the function renders it to themed HTML that works across Outlook Classic, New Outlook, Outlook Web, mobile clients and dark mode. * **One email per recipient** — when multiple recipients are supplied, the function sends an individual message to each address rather than a single multi-recipient mail. This is a privacy/BCC-by-default design. * **Inline branded header & footer** — bundled PNG assets are sent as CID attachments and referenced by the embedded HTML. Both can be overridden or suppressed entirely. * **Customizable template colors** — the accent and text color of the template can be overridden per call, so report emails can follow a customer's corporate design. * **Built-in attachment size guard** — an optional smaller fallback attachment set is sent automatically when the regular set exceeds the size budget or its send attempt fails. * **Self-connecting** — if no Graph session is active, the function transparently calls `Connect-RjRbGraph` (or `Connect-MgGraph -Identity` when `-UseNativeGraphRequest` is set). * **Resilient** — failed attachment reads, invalid image overrides, invalid colors, or per-recipient sendMail failures are reported but do not abort the entire batch unless *all* recipients fail. Centralized email settings (sender address, service desk info) are documented in [Runbook Report Settings](/automation/runbooks/runbook-report-settings.md) — this document focuses on calling the function from a runbook. ## Prerequisites ### Sender mailbox A licensed Microsoft 365 mailbox (typically a dedicated shared mailbox such as `realmjoin-report@contoso.com`) is required as the `From` address. The Automation Account's managed identity must be allowed to send on behalf of that mailbox via the Graph `Mail.Send` application permission (scoped via RBAC for Applications if you want to restrict the identity to a single mailbox). ### Graph permissions | Scenario | Required permission | | -------------------------------------- | ------------------------------------------------- | | Default (`Invoke-RjRbRestMethodGraph`) | `Mail.Send` (Application) on the sender mailbox | | With `-UseNativeGraphRequest` | Same — the call still hits `/users/{id}/sendMail` | ### Module connectivity By default the function uses `Invoke-RjRbRestMethodGraph` from this module. If no connection is active it auto-connects via `Connect-RjRbGraph`. When `-UseNativeGraphRequest` is set, the function instead checks `Get-MgContext` and calls `Connect-MgGraph -Identity -NoWelcome` on demand. ## Quick Start The minimum viable call requires only the sender, the recipient, a subject and the Markdown body: ```powershell Send-RjRbReportEmail ` -EmailFrom "realmjoin-report@contoso.com" ` -EmailTo "alice@contoso.com" ` -Subject "Weekly Report" ` -MarkdownContent @" # Weekly Report Hello Alice, here are this week's numbers: - New devices enrolled: **42** - License compliance: **98%** "@ ``` This produces a fully branded RealmJoin email with the default header and footer, light/dark mode support, and the tenant/version block in the footer. ## Parameters ### Required | Parameter | Type | Description | | ----------------- | -------- | ---------------------------------------------------------------------------------------------------------- | | `EmailFrom` | `string` | User principal name or object id of the sender mailbox. Used as `/users/{id}/sendMail`. | | `EmailTo` | `string` | Recipient address. **Single string** — multiple addresses are passed as a comma-separated list, see below. | | `Subject` | `string` | Subject line. Also injected into the HTML `` element. | | `MarkdownContent` | `string` | Report body in Markdown. See [Markdown Support](#markdown-support) for the supported syntax. | ### Optional — Content | Parameter | Type | Default | Description | | ------------------- | ---------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Attachments` | `string[]` | `@()` | Local file paths to attach. Missing files are logged and skipped, unreadable files emit a warning but do not abort the send. MIME type is derived from the file extension. | | `saveToSentItems` | `bool` | `$true` | If `$true` the sent message is kept in the sender mailbox's *Sent Items*. Set to `$false` for high-volume reporting to avoid filling the mailbox. | | `TenantDisplayName` | `string` | — | Shown in the tenant-info box embedded at the end of the content area. | | `ReportVersion` | `string` | — | Shown in the tenant-info box (use semantic version strings, build numbers, or a runbook name + date). | ### Optional — Branding | Parameter | Type | Default | Description | | ------------- | -------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `HeaderImage` | `string` | bundled `Assets/Header.png` | Local file path to a PNG/JPG/GIF that overrides the default header graphic. **The runbook must resolve any URL/blob to a local file beforehand** (e.g. via `Get-AzStorageBlobContent`). Missing/unreadable overrides fall back to the bundled default and emit a warning. | | `FooterImage` | `string` | bundled `Assets/Footer.png` | Same handling as `HeaderImage`. The footer is rendered as a single clickable image — any branding text, logo or URL must be baked into the PNG. | | `FooterLink` | `string` | `https://www.realmjoin.com` | URL used as the `href` and `title` of the anchor wrapping the footer image. | | `NoHeader` | `switch` | off | Suppresses the header graphic entirely. If combined with `HeaderImage`, a warning is emitted and the override is ignored. | | `NoFooter` | `switch` | off | Suppresses the footer graphic and its link entirely. If combined with `FooterImage` or a custom `FooterLink`, a warning is emitted and those values are ignored. | | `AccentColor` | `string` | `#f8842c` | *New in 0.8.9.* 6-digit hex color for table header rows, action buttons and the accent borders of the info boxes. An empty or malformed value emits a warning and falls back to the default. | | `TextColor` | `string` | `#011e33` | *New in 0.8.9.* 6-digit hex color for body text, headings, list items and code. Same fallback behavior as `AccentColor`. | **Recommended image dimensions:** 750 × 200 px PNG. This matches the email container width and the bundled defaults. Significantly different aspect ratios may look distorted on narrow viewports. Each graphic should stay well below 3 MB — Graph caps the total `sendMail` request at 4 MB and a warning is emitted if either image exceeds 3 MB. **Colors:** without `AccentColor`/`TextColor` the generated HTML is byte-for-byte identical to previous module versions — the defaults are the RealmJoin orange and navy. Status colors (green/red/amber) and neutral grays are intentionally not parameterized because they convey meaning. Verify custom colors in both light and dark mode: the content card stays white in dark mode, so a very light text color becomes unreadable. ### Optional — Attachment size guard *New in 0.8.9.* Graph rejects the whole `sendMail` request once the message exceeds \~4 MB. Instead of failing the report, the function can fall back to a smaller attachment set. This logic was previously duplicated as the inline runbook helper `Send-RjRbGuardedReportEmail` and is now part of the function itself. | Parameter | Type | Default | Description | | ------------------------- | ---------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `FallbackAttachments` | `string[]` | — | Smaller attachment set used when the regular set exceeds `MaxAttachmentBytes`, or when the send with the regular set fails for every recipient. Without this parameter there is no fallback and a failed send throws immediately. | | `FallbackMarkdownContent` | `string` | value of `MarkdownContent` | Body used when the fallback set is sent — use it to explain which files were left out and how to obtain them. | | `MaxAttachmentBytes` | `long` | `2.5MB` | Raw size budget for the regular attachment set. Stays safely below the \~4 MB Graph limit after base64 encoding (+33 %), HTML body and inline branding images. Only evaluated when `FallbackAttachments` is supplied. | The guard runs in two stages: 1. **Before sending** — if the regular set exceeds the budget, the fallback set is sent directly and a message names both sizes. 2. **After a failed send** — if the send with the regular set fails for *all* recipients, one retry with the fallback set is attempted before the function throws. ### Optional — Transport | Parameter | Type | Default | Description | | ----------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `UseNativeGraphRequest` | `switch` | off | Sends via `Invoke-MgGraphRequest` (requires `Microsoft.Graph` module and a `Connect-MgGraph` session) instead of `Invoke-RjRbRestMethodGraph`. Use this when the runbook is built around the native SDK rather than the RealmJoin wrapper. | ## Usage Examples ### Multiple recipients `EmailTo` accepts a single string containing one or more comma-separated addresses. Each address is trimmed, empty entries are removed, and **one individual email is sent per recipient** — recipients do not see each other. ```powershell Send-RjRbReportEmail ` -EmailFrom "realmjoin-report@contoso.com" ` -EmailTo "alice@contoso.com, bob@contoso.com, team-lead@contoso.com" ` -Subject "Monthly Inventory" ` -MarkdownContent $reportMd ``` ### With attachments and tenant metadata ```powershell $csvPath = Join-Path $env:TEMP 'devices.csv' $exportData | Export-Csv -Path $csvPath -NoTypeInformation -Encoding UTF8 Send-RjRbReportEmail ` -EmailFrom "realmjoin-report@contoso.com" ` -EmailTo "it-reports@contoso.com" ` -Subject "Device Inventory — $(Get-Date -Format 'yyyy-MM-dd')" ` -MarkdownContent $reportMd ` -Attachments @($csvPath, "$env:TEMP\summary.xlsx") ` -TenantDisplayName "Contoso Ltd" ` -ReportVersion "DeviceInventory v1.4.2" ``` The attached files are listed in an "Attached Files" box at the bottom of the email body, in addition to being added as real attachments to the message. ### Custom header/footer branding Bring your own branding by downloading the assets to a local path first, then pass the resulting paths. The function does not fetch URLs itself. ```powershell # Resolve branding assets from Azure Blob Storage to the runbook's temp folder $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-RjRbReportEmail ` -EmailFrom "realmjoin-report@contoso.com" ` -EmailTo "alice@contoso.com" ` -Subject "Branded Report" ` -MarkdownContent $reportMd ` -HeaderImage $headerPath ` -FooterImage $footerPath ` -FooterLink "https://intranet.contoso.com/it-reports" ``` If `$headerPath` is missing or unreadable, the call still succeeds — the bundled RealmJoin default is used and a warning is logged. ### Custom template colors Match the email to a customer's corporate design. Both parameters are independent — overriding only the accent color keeps the default text color: ```powershell Send-RjRbReportEmail ` -EmailFrom "realmjoin-report@contoso.com" ` -EmailTo "alice@contoso.com" ` -Subject "Branded Report" ` -MarkdownContent $reportMd ` -AccentColor "#0052cc" ` -TextColor "#1a1a2e" ``` An invalid value (for example `blue` or `#05c`) does not fail the send: a warning names the parameter and the default color is used. ### Large reports with a fallback attachment set Generate a CSV and an Excel workbook, but fall back to the workbook alone when the pair exceeds the size budget: ```powershell $sizeHint = "The CSV export was omitted because the attachments exceeded the email size limit. The Excel workbook contains the complete data." Send-RjRbReportEmail ` -EmailFrom "realmjoin-report@contoso.com" ` -EmailTo "it-reports@contoso.com" ` -Subject "Device Inventory" ` -MarkdownContent $reportMd ` -Attachments @($csvPath, $xlsxPath) ` -FallbackAttachments @($xlsxPath) ` -FallbackMarkdownContent ($reportMd + "`n`n> **Note:** $sizeHint") ``` Runbooks migrating from the inline helper `Send-RjRbGuardedReportEmail` can drop that function and rename the call to `Send-RjRbReportEmail` — the parameter names (`Attachments`, `FallbackAttachments`, `FallbackMarkdownContent`, `MaxAttachmentBytes`) are unchanged. ### Plain content (no header/footer) For alert-style notifications that should not look like a marketing email: ```powershell Send-RjRbReportEmail ` -EmailFrom "realmjoin-report@contoso.com" ` -EmailTo "oncall@contoso.com" ` -Subject "[ALERT] License threshold exceeded" ` -MarkdownContent "## License threshold exceeded`n`nSee dashboard for details." ` -NoHeader ` -NoFooter ``` ### Using the native Microsoft.Graph SDK If the runbook is already authenticated through `Connect-MgGraph` (managed identity) and you prefer not to mix in the RealmJoin wrapper: ```powershell Connect-MgGraph -Identity -NoWelcome Send-RjRbReportEmail ` -EmailFrom "realmjoin-report@contoso.com" ` -EmailTo "alice@contoso.com" ` -Subject "Native Graph send" ` -MarkdownContent $reportMd ` -UseNativeGraphRequest ``` ### Reading the report body from a file For larger reports, generate the Markdown to a `.md` file and read it in: ```powershell $reportMd = Get-Content -Path .\generated-report.md -Raw Send-RjRbReportEmail ` -EmailFrom "realmjoin-report@contoso.com" ` -EmailTo "alice@contoso.com" ` -Subject "Weekly Report" ` -MarkdownContent $reportMd ``` ### Action buttons (call-to-action) Render one or more branded buttons by appending `{button}` to a Markdown link. Buttons placed on the same line are grouped into a single row: ```powershell $reportMd = @" # Access request A new device access request is awaiting your decision. [Approve](https://portal.contoso.com/approve/123){button} [Reject](https://portal.contoso.com/reject/123){button} "@ Send-RjRbReportEmail ` -EmailFrom "realmjoin-report@contoso.com" ` -EmailTo "approver@contoso.com" ` -Subject "Action required: device access request" ` -MarkdownContent $reportMd ``` Each button is a normal hyperlink styled as a CTA — safe in all clients, with rounded corners in modern clients and square corners in Outlook Classic. ## Markdown Support The function ships with a built-in lightweight Markdown → HTML converter. **No external Markdown module is required.** Supported syntax: | Markdown | Notes | | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `# … ######` headings | All six levels. Space after `#` is optional. `h1` gets an underline; spacing tuned for Outlook. | | `**bold**`, `*italic*`, `~~strike~~` | Inline-only (must not span multiple lines). | | `` `inline code` `` | Rendered as `<code>` with a light grey background. | | lang ... fenced code blocks | Language tag is preserved as `class="language-…"`. Also tolerates malformed single-backtick fences. | | `[text](url)` links | Open in new tab with `noopener noreferrer`. | | `[label](url){button}` link buttons | Rendered as a branded orange call-to-action button instead of a plain link. Multiple `{button}` links on the **same line** render side by side in one row (width split equally). Rounded corners show in modern clients (New Outlook, OWA, mobile); Outlook Classic (Word engine) renders square corners. | | `![alt](url)` images | Inserted as `<img>` (no inline-attachment magic — the URL must be reachable by the mail client). | | `- item` / `1. item` lists | Nested lists supported via 2-space indentation per level. Mixing ordered and unordered closes the previous list. | | Multi-line list items | An indented, non-empty line directly under a `<li>` is folded into the same item with a `<br>` soft break — no need to keep each item on one line. | | `- [ ]` / `- [x]` task lists | Rendered as `☐` / `☑` Unicode glyphs (green when checked). `<input type="checkbox">` is intentionally avoided because Outlook Classic strips form controls. Capital `[X]` also counts as checked. | | `> blockquote` | Rendered with a coloured left border and shaded background. | | `> [!NOTE\|TIP\|IMPORTANT\|WARNING\|CAUTION]` | GitHub-style admonitions. First line of the blockquote is the marker (alone), the remaining `>`-prefixed lines are the body. Each type gets its own accent colour, glyph and title bar. | | `---`, `***`, `___` | Horizontal rule. | | `\|col\|col\|` tables | Standard pipe tables with `:---`, `:---:`, `---:` alignment specifiers. Header row + separator required. | | `\\` escaping | `\*`, `\|` etc. are honoured so literal Markdown characters can be emitted. | Items not supported include footnotes, definition lists, and HTML pass-through — keep the Markdown to the table above. ## Behavior & Error Handling ### Recipient parsing `EmailTo` is split on commas, each entry is trimmed and empty entries are dropped. If the resulting list is empty the function throws `No valid email recipients found in EmailTo parameter.` before any Graph call is made. ### Per-recipient failures Each recipient is sent independently. The function tracks successes and failures: * If **at least one** send succeeds but others fail, a warning is emitted listing the failed addresses; the function returns normally. * If **all** sends fail, the function throws `Failed to send email to all recipients: …` so the runbook fails loudly. ### Attachment failures * Missing files (path does not exist) — logged verbosely, silently skipped. * Existing but unreadable files (locked, permission denied) — warning emitted, skipped, the rest of the call proceeds. * The "Attached Files" box at the bottom of the email lists only attachments that were successfully read. ### Image override failures Both `HeaderImage` and `FooterImage` fall back to the bundled defaults on any error (missing file, IO error, or a file that is not a valid image). A warning describes the failure and identifies which default was used. Since 0.8.9 the image format is determined from the **file signature** (magic bytes) rather than the file extension. A file that is named `.png` but actually contains an HTML error page — a common outcome when a download silently returns an error document — is now rejected with a warning instead of producing a broken inline attachment. Conversely, a valid PNG saved under a misleading extension is accepted and typed correctly. ### Invalid colors `AccentColor` and `TextColor` are validated against `^#[0-9A-Fa-f]{6}$`. A value that does not match emits a warning naming the parameter and the send proceeds with the default color. Colors are never a reason for a report to fail. ### Total size limit Graph caps `sendMail` requests at \~4 MB combined (HTML body + all attachments, base64-encoded). The function emits a warning when either branding image exceeds 3 MB. When `FallbackAttachments` is supplied, the attachment size guard described in the parameter section above handles oversized payloads automatically. Without a fallback set, an oversized request fails in the Graph call; consider: * Supplying a `FallbackAttachments` set (for example the Excel workbook without the raw CSV files). * Uploading large data to the Storage Account channel instead — see [Runbook Report Settings](/automation/runbooks/runbook-report-settings.md#storage-account-delivery). * Linking to externally hosted attachments rather than embedding them. * Compressing tabular data (`Compress-Archive`) before attaching. ## Integration with Runbook Report Settings Reporting runbooks do not hard-code the sender address or branding: they declare hidden parameters that the RealmJoin portal prefills from the central customization JSON. The available settings are documented in [Runbook Report Settings](/automation/runbooks/runbook-report-settings.md). The binding happens in the runbook's `param()` block via `Use-RJInterface -Type Setting`, and the parameters are marked `"Hide": true` in the `.INPUTS RunbookCustomization` block so they do not clutter the portal form: ```powershell param( [ValidateScript( { Use-RJInterface -Type Setting -Attribute "RJReport.EmailSender" -Value $_ } )] [string]$EmailFrom, [ValidateScript( { Use-RJInterface -Type Setting -Attribute "RJReport.Branding.HeaderImageUrl" -Value $_ } )] [string]$BrandingHeaderImageUrl, [ValidateScript( { Use-RJInterface -Type Setting -Attribute "RJReport.Branding.FooterImageUrl" -Value $_ } )] [string]$BrandingFooterImageUrl, [ValidateScript( { Use-RJInterface -Type Setting -Attribute "RJReport.Branding.FooterLink" -Value $_ } )] [string]$BrandingFooterLink, [ValidateScript( { Use-RJInterface -Type Setting -Attribute "RJReport.Branding.AccentColor" -Value $_ } )] [string]$BrandingAccentColor, [ValidateScript( { Use-RJInterface -Type Setting -Attribute "RJReport.Branding.TextColor" -Value $_ } )] [string]$BrandingTextColor ) if (-not $EmailFrom) { throw "No EmailSender configured. See https://docs.realmjoin.com/automation/runbooks/runbook-report-settings for setup instructions." } # Download and validate the branding images once per run; returns only the keys # that resolved successfully, so unset settings fall through to the defaults. $brandingMailParams = Get-RjRbBrandingMailParams ` -HeaderImageUrl $BrandingHeaderImageUrl ` -FooterImageUrl $BrandingFooterImageUrl ` -FooterLink $BrandingFooterLink ` -AccentColor $BrandingAccentColor ` -TextColor $BrandingTextColor Send-RjRbReportEmail ` -EmailFrom $EmailFrom ` -EmailTo $RecipientParameter ` -Subject $Subject ` -MarkdownContent $reportMd ` -TenantDisplayName $TenantDisplayName ` -ReportVersion "MyReport v1.0" ` @brandingMailParams ``` See [Get-RjRbBrandingMailParams](/dev-reference/report-functions/get-rjrbbrandingmailparams.md) for the download, validation and cleanup rules. ## Outputs The function returns nothing on success. All progress is written via `Write-RjRbLog -Verbose` (visible when the runbook is run with `-Verbose` or `$VerbosePreference = 'Continue'`). Warnings are forced through `$WarningPreference = 'Continue'` regardless of caller-side overrides, so they reliably appear in the Azure Automation job stream. ## Related Exported Helpers The building blocks behind `Send-RjRbReportEmail` are now exported from the module too, so runbooks can compose or preview the HTML without sending: | Function | Purpose | | --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [`Get-RjRbBrandingMailParams`](/dev-reference/report-functions/get-rjrbbrandingmailparams.md) | Turns the `RJReport.Branding.*` tenant settings into ready-to-splat parameters: downloads and validates the images, passes colors and footer link through. | | `ConvertFrom-RjRbMarkdownToHtml` | Standalone Markdown → HTML converter (the same lightweight engine used internally, including the `{button}` syntax). Accepts `-AccentColor`/`-TextColor`. | | `Get-RjRbReportEmailBody` | Assembles the full branded HTML body (header/footer, tenant-info box, attachment list) from HTML or Markdown — useful to render and inspect the email before sending. Accepts `-AccentColor`/`-TextColor`. | | `Resolve-RjRbImageSource` | Resolves a header/footer image path to its inline CID source. Validates by file signature and throws on anything that is not a PNG, JPEG or GIF. | Except for `Get-RjRbBrandingMailParams`, these are primarily intended for advanced/testing scenarios; the normal path is to call `Send-RjRbReportEmail` directly. ## See Also * [Get-RjRbBrandingMailParams](/dev-reference/report-functions/get-rjrbbrandingmailparams.md) — resolving the tenant branding settings inside a runbook. * [Runbook Report Settings](/automation/runbooks/runbook-report-settings.md) — central configuration of the sender mailbox, service desk info, branding, and Storage Account delivery channel. * Microsoft Graph: [Send mail](https://learn.microsoft.com/en-us/graph/api/user-sendmail) — underlying API. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.realmjoin.com/dev-reference/report-functions/send-rjrbreportemail.md?ask=<question>&goal=<endgoal> ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.