HTML e-mail reports from PowerShell that look good on phone and desktop
Structure, inline CSS, status colours, tables and sending of an HTML report that renders well on phone and desktop.
A script that sends a plain-text report with columns aligned by spaces only reads well in a monospace font on a big screen. Yet operations reports are often read on a phone. Here is how I build clean HTML e-mails from PowerShell that hold up at 390 px as well as 1024 px.
Principles
- One status per mail (ERROR, ACTION, WARNING, OK, INFO), derived from the data and visible on the first screen.
- Summary in the body, detail in an attachment: tables of 4 columns at most, the rest in a CSV.
- Phone first: no horizontal scrolling, text of 12 px minimum, 44 px buttons.
- Data is shown as produced, but always HTML-encoded: an error message containing
<must never turn into markup. - Never lose a mail: if building the HTML fails, send a short plain body with the same subject.
Structure of a mail
Mail clients (especially classic Outlook, which renders with Word) ignore a lot of modern CSS. I stick to:
- tables for layout (
role="presentation"), neverflexorgrid; - inline CSS on every cell; a
<style>block is only for media queries and dark mode, so the mail stays complete without it; - a central card with
max-width:720px, full width on a phone; bgcolorin addition tobackground-coloron coloured cells (Outlook);- no images, no web fonts, no emoji: icons invert badly in dark mode, the status word carries the meaning.
Status colours
I define six tones, each with dark text on a light background of the same hue, which stays readable even when the client forces its own dark mode. ACTION gets a different hue (violet) so it never looks like WARNING.
| Tone | Text | Background |
|---|---|---|
| error | #b42318 |
#fef3f2 |
| action | #5925dc |
#f4f3ff |
| warning | #b54708 |
#fffaeb |
| ok | #027a48 |
#ecfdf3 |
| info | #175cd3 |
#eff8ff |
A short example
function ConvertTo-MailTable {
param([object[]]$Rows)
$tone = @{ FAILED = '#b42318;#fef3f2'; WARNING = '#b54708;#fffaeb'; OK = '#027a48;#ecfdf3' }
$cells = foreach ($r in $Rows) {
$fg, $bg = ($tone[$r.Status.ToUpper()] ?? '#475467;#f2f4f7') -split ';'
$name = [System.Net.WebUtility]::HtmlEncode($r.Name)
"<tr><td bgcolor='$bg' style='background-color:$bg;color:$fg;font:700 12px Segoe UI,Arial;padding:9px 12px'>$($r.Status.ToUpper())</td>" +
"<td style='font:14px/20px Segoe UI,Arial;color:#1d2939;padding:9px 10px;border-bottom:1px solid #eaecf0'>$name</td></tr>"
}
"<table role='presentation' width='100%' cellpadding='0' cellspacing='0'>$($cells -join '')</table>"
}
$rows = @(
[pscustomobject]@{ Name = 'nightly-export'; Status = 'ok' }
[pscustomobject]@{ Name = 'index-maintenance'; Status = 'failed' }
)
$worst = if ($rows.Status -contains 'failed') { 'ERROR' } else { 'OK' }
$html = @"
<!doctype html><html><head><meta charset='utf-8'>
<meta name='viewport' content='width=device-width,initial-scale=1'>
<title>[$worst] Jobs - daily</title></head>
<body style='margin:0;background:#f4f5f7'>
<table role='presentation' width='100%'><tr><td align='center' style='padding:16px'>
<table role='presentation' width='100%' style='max-width:720px;background:#ffffff'><tr><td style='padding:20px 24px'>
<h1 style='font:600 22px/28px Segoe UI,Arial;color:#101828;margin:0 0 12px'>Daily job report - $worst</h1>
$(ConvertTo-MailTable -Rows $rows)
</td></tr></table></td></tr></table></body></html>
"@
The table has only two columns: status first (a tinted cell), then the name. An extra field becomes a grey line under the name rather than a fifth column.
Sending
Send-MailMessage is marked obsolete by Microsoft. I prefer a service that accepts HTML through an API, for example Microsoft Graph:
Send-MgUserMail -UserId 'dba@contoso.com' -Body @{
Message = @{
Subject = "[$worst] Jobs - daily"
Body = @{ ContentType = 'HTML'; Content = $html }
ToRecipients = @(@{ EmailAddress = @{ Address = 'team@contoso.com' } })
}
}
The subject follows a fixed pattern, [STATUS] Application env - summary, in ASCII: inbox rules rely on it.
Lessons learned
- Test at 390 px, not only at 1024 px. A headless browser cannot go below about 500 px: render the HTML in an iframe of exact width.
- Never test by mailing the real distribution list.
- The preheader (the grey text in the inbox list) is hidden text at the start of the body: put the verdict and the action to take there.
- Gmail clips mails above 100 KB: cap the rows (25 in an action list, 10 in an information table) and point to an attached CSV for the rest (
;separator, UTF-8 with BOM so Excel opens it directly). - "Could not check" is an error state, never a silent OK.