Inspect RFC 822 mail with gpgparsemail

You will feed a mail message to gpgparsemail and read its annotated representation, including the headers it parsed and the body or MIME information it recognised. This is a diagnostic tool, not a mail delivery command. Allow about ten minutes for a first check. You need a shell, the gnupg-utils package, and a mail message that you are allowed to inspect.

The installed command is from GnuPG 2.4.4, package version 2.4.4-2ubuntu17.6 on this system. The local manual describes it as useful for debugging and warns that it is under development. Its output semantics can change, so treat the examples here as a guide to this installed version rather than a stable machine-readable interface.

1. Check the installed command

Start by checking which executable will run and asking it for its own usage text:

$ command -v gpgparsemail
/usr/bin/gpgparsemail
$ gpgparsemail --help
Usage: gpgparsemail [OPTION] [FILE]
Parse a mail message into an annotated format.

The help text lists four useful switches: --crypto to decrypt or verify messages, --no-header to suppress parsed header lines, --verbose for extra information, and --debug for additional parser events. With no file, or with - as the file, the command reads standard input.

Checkpoint: if command -v finds nothing, install or repair the package through your normal system administration process. Do not use sudo merely to parse a message that your user can already read.

2. Parse a message from standard input

For a quick, non-destructive test, pipe a small RFC 822 message into the command. The example uses CRLF line endings, as mail transport normally does:

$ printf 'From: Alice <[email protected]>\r\nTo: Bob <[email protected]>\r\nSubject: Test message\r\nDate: Thu, 24 Sep 2026 10:00:00 +0000\r\n\r\nHello Bob.\r\n' | gpgparsemail
.From: Alice <[email protected]>
.To: Bob <[email protected]>
.Subject: Test message
.Date: Thu, 24 Sep 2026 10:00:00 +0000
h media: text plain [assumed]
 Hello Bob.

The leading dot marks the header lines in this annotated output. The h media line shows that the parser treated the body as plain text when no more specific content type was supplied. The leading space on the following line is part of the annotation style. Do not mistake this display for a cleaned-up copy of the original message.

A useful status check is:

$ printf 'Subject: Test\r\n\r\nBody\r\n' | gpgparsemail >/tmp/gpgparsemail.out
$ printf '%s\n' "$?"
0

Writing diagnostic output to a temporary file makes it easier to inspect without changing the source message. Remove that temporary file when it contains sensitive mail. This does not alter the message supplied on standard input.

3. Parse an existing mail file

Pass one file after the options. The input is read, not rewritten:

$ gpgparsemail /path/to/message.eml
.From: Alice <[email protected]>
.To: Bob <[email protected]>
.Subject: Test message
h media: text plain [assumed]
 Hello Bob.

Use a path to a copy when investigating an uncertain or valuable message. The command has no output-file option in the installed help, so its annotated result goes to standard output. Redirecting with > creates or truncates the destination before parsing begins:

$ gpgparsemail /path/to/message.eml > /tmp/message-annotated.txt
$ test -s /tmp/message-annotated.txt && echo 'annotation written'
annotation written

Do not redirect over the original .eml file. Keep the original message intact so you can compare it with later output or pass it to another diagnostic tool.

4. Hide headers when focusing on the body

Use --no-header when the header annotations are distracting:

$ gpgparsemail --no-header /path/to/message.eml
h media: text plain [assumed]
 Hello Bob.

This option suppresses the displayed header lines. It does not remove headers from the input, repair malformed fields, or make the output suitable for forwarding. If you need to diagnose a missing subject, recipient, or date, leave this option off.

Checkpoint: compare both forms against the same input. The body and MIME-related annotations should remain, while the lines beginning with a dot disappear:

$ gpgparsemail /path/to/message.eml > /tmp/with-headers.txt
$ gpgparsemail --no-header /path/to/message.eml > /tmp/without-headers.txt
$ diff -u /tmp/with-headers.txt /tmp/without-headers.txt

The exact diff depends on the message. A non-empty diff containing the annotated header lines is expected.

5. Add parser diagnostics only when needed

Start with ordinary output. If it does not explain a parsing result, add --verbose:

$ gpgparsemail --verbose /path/to/message.eml > /tmp/message-verbose.txt

Extra warnings are written to the terminal in addition to the annotated output. For event-level investigation, use --debug:

$ gpgparsemail --debug /path/to/message.eml > /tmp/message-debug.txt
# *** got RFC822 event Open
# *** got RFC822 event Begin_Header
# *** got RFC822 event T2Body
# *** got RFC822 event Close

The event names show how far the parser progressed. Debug text is for a human investigating one message, not for a script that depends on an undocumented event format. If you need to preserve both standard output and diagnostic messages, redirect them separately only after confirming which stream your local test uses.

6. Handle line-ending and content traps

A message assembled with ordinary shell newlines may still be accepted, but this installed version can report a warning such as non canonical ended line detected. Re-test with CRLF input before treating that warning as a message-content failure. Mail copied through a web page or text editor can also contain altered line endings, folded headers, or missing blank lines.

The parser's plain-text example says [assumed] because the test message did not include a Content-Type header. That is a parsing assumption, not proof that the sender declared plain text. Inspect the original headers before drawing conclusions about MIME structure.

Do not enable --crypto casually. It asks the tool to decrypt or verify messages and can involve private keys, trust decisions, passphrase prompts, or sensitive plaintext. Use it only when you understand the message's origin and the key material available to the current account. A normal syntax or MIME investigation does not require elevated privileges or cryptographic processing.