Inspect RFC 822 Mail with gpgparsemail

gpgparsemail takes a mail message and prints an annotated view of the headers and body it recognised. It is a diagnostic tool, not a mail delivery command, and it never rewrites the message you give it. 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.
• Installed version: GnuPG 2.4.4, package version 2.4.4-2ubuntu17.6 on this system.
• Treat it as unstable. The local manual calls it useful for debugging and warns that it is under development; 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.

• --crypto decrypts or verifies messages.
• --no-header suppresses parsed header lines.
• --verbose adds extra information.
• --debug adds parser events.

With no file, or with - as the file, the command reads standard input.

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, and 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

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.

$ 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.