MailHeaderAnalyzer: Analyze Email Headers in PowerShell Without Network Access

MailHeaderAnalyzer is a PowerShell module with two cmdlets. Get-MailHeaderAnalysis analyzes an email header: the delivery chain with delays and TLS details, SPF, DKIM, DMARC, and ARC results including verification of whether those results originated from the receiving server, DMARC alignment, the Exchange Online hybrid classification, ratings from Microsoft Defender, SpamAssassin, and Rspamd, as well as anomalies such as duplicate From lines or Unicode control characters. ConvertTo-MailHeaderReport creates a report for tickets. The module works entirely offline: no DNS lookups, no HTTP connections. It is the command-line version of the Header Analyzer on this website and uses the same analysis logic.

Parameter overview

Both cmdlets support the common parameters -Verbose, -ErrorAction, -ErrorVariable, -OutVariable and the others from about_CommonParameters.

Installation

Install-Module -Name MailHeaderAnalyzer -Scope CurrentUser

On a system without internet access, download the module on another computer with Save-Module -Name MailHeaderAnalyzer -Path C:\Temp and copy the MailHeaderAnalyzer folder to a directory in $env:PSModulePath, for example %USERPROFILE%\Documents\WindowsPowerShell\Modules (Windows PowerShell 5.1) or %USERPROFILE%\Documents\PowerShell\Modules (PowerShell 7). Update-Module -Name MailHeaderAnalyzer retrieves updates, and Get-Module -Name MailHeaderAnalyzer -ListAvailable shows the installed version.

Get-MailHeaderAnalysis

Analyzes an email header and returns an analysis object.

Syntax

Text (default)

Get-MailHeaderAnalysis
    [-Header] <String[]>
    [<CommonParameters>]

Path

Get-MailHeaderAnalysis
    -Path <String[]>
    [<CommonParameters>]

Clipboard

Get-MailHeaderAnalysis
    -FromClipboard
    [<CommonParameters>]

Description

The cmdlet splits the raw header into fields, unfolds RFC 5322 folding, and decodes RFC 2047 values in subjects and addresses. From the Received lines, it builds the delivery chain in chronological order, calculates the delay at each station, and reads the TLS version, cipher, and protocol class according to RFC 3848. From Authentication-Results, Received-SPF, DKIM-Signature, and the ARC chain, it determines authentication results and checks whether the verification line actually originated from a station in the delivery chain (RFC 8601, section 5). It also includes DMARC alignment, the Exchange Online hybrid classification, spam filter ratings, and a list of anomalies.

The cmdlet performs no DNS lookups and opens no network connection. Spf, Dkim, and Dmarc are therefore always the receiving server’s judgment, supplemented by verification of whether that judgment originated from it. DKIM signatures are not cryptographically revalidated.

Input is read tolerantly: a blank line ends the header, and any following message body is ignored. Lines without a field name and without leading whitespace, as can occur when copying from client dialogs, belong to the preceding field. An mbox separator line From ... before the first field is skipped, and a Byte Order Mark is removed. At most 200 Received lines are analyzed, counted from delivery.

Examples

Example 1

Get-MailHeaderAnalysis -FromClipboard

Analyzes the header in the clipboard. In Outlook for Windows, you can find the header under File, Properties, Internet headers; in Outlook on the web, find it in Message options under “View message details.”

Subject     : Service-Report für März
From        : Beispiel Newsletter <[email protected]>
Date        : 2026-08-03 09:14:27Z
SPF         : pass
DKIM        : pass
DMARC       : pass
ARC         : -
CompAuth    : pass (reason 100)
AuthTrust   : Absent (no authserv-id, Microsoft 365 style)
Hops        : 3 (total 00:00:42)
DeliveredBy : zr0p278mb0570.chep278.prod.outlook.com
Findings    : none

Example 2

Get-MailHeaderAnalysis -Path .\nachricht.eml

Analyzes a saved message. The file may contain only the header or the complete message; the message body is ignored.

Example 3

(Get-MailHeaderAnalysis -Path .\nachricht.eml).Hops

Shows the delivery chain as a table, first hop first.

#   From                 IP              By                                     Protocol   TLS      Time (UTC)           Delay
-   ----                 --              --                                     --------   ---      ----------           -----
1   client.example.net   198.51.100.34   mail.example.org                       ESMTPSA    -        2026-08-03 09:14:28  -
2   mail.example.org     203.0.113.25    mx.eur02.prod.protection.outlook.com   Microsoft… TLS 1.3  2026-08-03 09:15:09  41 s
3   AM0EUR02FT056.eop…   -               ZR0P278MB0570.CHEP278.PROD.OUTLOOK.COM Microsoft… TLS 1.2  2026-08-03 09:15:10  1 s

Example 4

Get-Content -Path .\header.txt | Get-MailHeaderAnalysis | Select-Object -ExpandProperty Findings

Reads the header line by line from a text file and shows only anomalies. -Raw with Get-Content is not necessary; the cmdlet combines the lines itself.

Example 5

Get-ChildItem -Path .\export\*.eml |
    Get-MailHeaderAnalysis |
    Select-Object Source, Subject, Spf, Dkim, Dmarc, AuthTrust, HopCount,
        @{ Name = 'Findings'; Expression = { ($_.Findings.Code | Sort-Object -Unique) -join ',' } } |
    Export-Csv -Path .\auswertung.csv -NoTypeInformation -Encoding UTF8

Analyzes all messages in a folder and writes a CSV file with one row per message. The calculated column combines the finding codes.

Example 6

Get-ChildItem .\export\*.eml |
    Get-MailHeaderAnalysis |
    Where-Object AuthTrust -eq 'Unmatched' |
    Select-Object Source, AuthServId, DeliveredBy

Lists messages whose Authentication-Results line does not originate from the delivering system. This is a quick first filter in phishing analysis.

Example 7

$a = Get-MailHeaderAnalysis -Path .\nachricht.eml
$a.Hops[$a.SlowestHopIndex - 1] | Format-List Index, FromHost, ByHost, Delay

Shows the station with the longest delay. SlowestHopIndex is 1-based, while the Hops array is 0-based.

Example 8

Get-MailHeaderAnalysis -Path .\nachricht.eml | ConvertTo-Json -Depth 6 | Set-Content .\analyse.json

Writes the complete analysis as JSON. -Depth 6 is necessary because Hops, DkimSignatures, and Exchange are nested objects; the default value of 2 would output only their type names.

Parameters

-Header

The header as text. The parameter accepts a single string containing the entire header or multiple strings; pipeline input is collected and combined into one header at the end, so Get-Content datei | Get-MailHeaderAnalysis works without -Raw. To analyze multiple headers separately, use -Path with multiple files.

Aliases: Text, Raw, InputObject

-Path

Path to a file containing the header or a complete .eml message. Relative paths are resolved against the current directory. The file is read with [System.IO.File]::ReadAllText: a Byte Order Mark is honored; without a BOM, UTF-8 is used. Each file produces a separate result object; missing files produce a non-terminating error.

Aliases: FullName, PSPath, LiteralPath

-FromClipboard

Reads the header from the clipboard with Get-Clipboard -Raw. The parameter is available only on Windows; on Linux and macOS, the cmdlet terminates with an error, as it does if the clipboard is empty.

Inputs

System.String: header lines or the entire header, to -Header.

System.IO.FileInfo: file objects from Get-ChildItem, whose FullName is bound to -Path.

Outputs

MailHeaderAnalyzer.Analysis: one object per analyzed header. The properties are described in the Output object section.

Notes

The analysis text (explanations in Findings, CompAuthReasonMeaning, and the meaning fields) is in English so it can be used unchanged in international tickets. You can display the default view in full with Format-List *.

ConvertTo-MailHeaderReport

Creates a report in Markdown or text from an analysis object.

Syntax

ConvertTo-MailHeaderReport
    [-Analysis] <Object>
    [-Format <String>]
    [<CommonParameters>]

Description

The report includes the subject, sender, date, and Message-ID; authentication results with origin and alignment; all findings; the delivery chain; the Exchange classification; and spam filter values. Unicode control characters for text direction remain visible in the report as <U+...> so they cannot reach a ticket system through the report. The last line states the module version.

Examples

Example 1

Get-MailHeaderAnalysis -Path .\nachricht.eml | ConvertTo-MailHeaderReport | Set-Clipboard

Creates a Markdown report and places it in the clipboard.

# Email header analysis

- Subject: Service-Report für März
- From: Beispiel Newsletter <[email protected]>
- Date: 2026-08-03T09:14:27Z
- Message-ID: <[email protected]>

## Authentication

- spf: pass
- dkim: pass
- dmarc: pass
- compauth: pass (reason=100: passed authentication)
- Results without authserv-id (Microsoft 365 style)
- DMARC alignment: SPF Strict, DKIM Strict

## Delivery chain (total: 42 s)

| # | From | By | Protocol | TLS | Time (UTC) | Delay |
|---|---|---|---|---|---|---|
| 1 | client.example.net (198.51.100.34) | mail.example.org | ESMTPSA | - | 2026-08-03T09:14:28Z | - |
| 2 | mail.example.org (203.0.113.25) | mx.eur02.prod.protection.outlook.com | Microsoft SMTP Server | TLS 1.3 | 2026-08-03T09:15:09Z | 41 s |
| 3 | AM0EUR02FT056.eop-EUR02.prod.protection.outlook.com | ZR0P278MB0570.CHEP278.PROD.OUTLOOK.COM | Microsoft SMTP Server | TLS 1.2 | 2026-08-03T09:15:10Z | 1 s |

Example 2

Get-MailHeaderAnalysis -FromClipboard | ConvertTo-MailHeaderReport -Format Text

Outputs the report as text without Markdown formatting, for example for emails or console logs.

Example 3

Import-Module MailHeaderAnalyzer
Get-MailHeaderAnalysis -Path 'C:\Temp\bounce.eml' | ConvertTo-MailHeaderReport -Format Text

Use in the Exchange Management Shell. If $env:PSModulePath is restricted there by Group Policy, load the module with Import-Module and the full path to the .psd1 file.

Parameters

-Analysis

The analysis object from Get-MailHeaderAnalysis. The cmdlet rejects other object types with a binding error.

-Format

The output format. Valid values:

• Markdown: headings, lists, and the delivery chain as a table. Default.
• Text: uppercase headings, indented lines, and the delivery chain as a numbered list.

Inputs

MailHeaderAnalyzer.Analysis: the result of Get-MailHeaderAnalysis.

Outputs

System.String: the report, one string per analysis object.

Output object

Get-MailHeaderAnalysis returns one object of type MailHeaderAnalyzer.Analysis per input. The default view shows the summary from Example 1; all properties are available through Select-Object, Format-List *, or ConvertTo-Json.

MailHeaderAnalyzer.Analysis

MailHeaderAnalyzer.Hop

Each entry in Hops corresponds to one Received line. The order is chronological, thus the reverse of the order in the header.

AuthTrust: Origin of verification results

Any sender can write an Authentication-Results line into a message. Under RFC 8601, section 5, only the line from the receiving organization is authoritative, and its authserv-id must be assignable to a station in the delivery chain. The cmdlet compares each line’s authserv-id with the by hosts in the Received chain (same domain or subdomain, always at a dot boundary, never a substring).

If the header contains verification lines from multiple origins, finding AuthMixedOrigins reports this. If a verification line is missing but a Received-SPF line is present, its result is adopted as Spf and labeled ReceivedSpfOnly.

DMARC alignment

SpfAlignment compares the envelope sender domain with the From domain, while DkimAlignment compares the d= domain of the verified signature with the From domain. Strict means identical domains, Relaxed means the same organizational domain, and None means no match. The organizational domain is determined heuristically: the last two labels, or the last three for known multi-part suffixes such as co.uk or com.au. A complete Public Suffix List is not included.

MailHeaderAnalyzer.ExchangeClassification

If the header contains X-MS-Exchange-Organization-*, X-OriginatorOrg, or X-MS-Exchange-CrossTenant-* fields, the cmdlet populates the Exchange property. The meanings follow the Exchange Team article “Demystifying hybrid mail flow”; background information is available in the article Exchange Hybrid Headers: Internal or External?.

MailHeaderAnalyzer.SpamAssessment

The Spam property summarizes ratings from known filters. Values originate from third-party systems and are decoded but not assessed.

The complete list of compauth reason codes is available in the article Microsoft 365 compauth: Reason Codes.

Findings

The cmdlet returns anomalies as objects in Findings, each with Severity (Info, Warning, Fail), a stable Code for filters and scripts, and an explanation in Message.

How it works and limitations

The module reads what is in the header and infers what can be established without external queries. This results in several limitations:

• No cryptographic verification. DKIM signatures are not revalidated and DNS records are not queried. Spf, Dkim, and Dmarc are always the receiving server’s judgment, supplemented by verification of whether that judgment originated from it at all.
• Only the last Received line is substantiated. The sender supplied all lines below it and could have composed them arbitrarily. Attested marks this distinction; delays for earlier hops are based on the information in those lines.
• Organizational domains are heuristic. For relaxed alignment, the module uses a short list of multi-part suffixes, not a complete Public Suffix List.
• AuthMechanism is only partially documented. Apart from value 10, Microsoft has not published the codes; the module does not invent meanings.
• Character sets. RFC 2047 values are decoded using the encodings known to .NET on the respective system. Unknown character sets remain unchanged.

Privacy

A complete header contains internal host names, IP addresses, senders, recipients, and subjects. The article Analyze email headers without uploading the email explains why this information does not belong in an online tool. The same promise applies to the module as to the browser version: no network access. The module’s test suite includes a test that fails as soon as a network or DNS cmdlet appears in the source code.

Source code and versions

The source code is available under the MIT License on GitHub. The analysis logic is a port of the library also used by the Header Analyzer on this website; both share the test cases. Continuous Integration checks every change with PSScriptAnalyzer and Pester on Windows PowerShell 5.1, PowerShell 7 on Windows, Ubuntu, and macOS. Releases to the PowerShell Gallery are made automatically from versioned tags; changes for each version are listed in the Changelog.

I accept bugs and feature requests as GitHub issues. Please anonymize test headers before submitting bug reports; the included test cases use only example domains under RFC 2606 and addresses under RFC 5737.