LLI Wiki — My Digital Knowledge Base

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

  1. One status per mail (ERROR, ACTION, WARNING, OK, INFO), derived from the data and visible on the first screen.
  2. Summary in the body, detail in an attachment: tables of 4 columns at most, the rest in a CSV.
  3. Phone first: no horizontal scrolling, text of 12 px minimum, 44 px buttons.
  4. Data is shown as produced, but always HTML-encoded: an error message containing < must never turn into markup.
  5. 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:

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

Mastodon LLIMastodon SocialFosstodon