Analyze Email Headers from the Terminal

What are email headers and which ones matter?

Email headers are the metadata fields above the body of every message, defined by RFC 5322. A typical message carries 20 to 40 of them, but only a handful matter for tracing delivery and catching spoofing: Received, Authentication-Results, Message-ID, and the From and Return-Path addresses.

The body is what a person reads; the headers are what the mail infrastructure wrote. Each relay that touched the message stamped a Received line, and the receiving server recorded its SPF, DKIM, and DMARC checks. That audit trail is why a forged sender address still leaves fingerprints a few lines down. Reading it from the terminal beats clicking through a webmail “show original” dialog for every message you triage.

How do I dump an email's headers from the CLI?

The nylas email read <message-id> --headers command prints the full header block for any message, normalized across every provider so Gmail, Microsoft 365, and IMAP accounts return the same field names. Add --mime when you need the raw RFC822 source, including header folding and exact byte order.

Start by finding a message ID. The nylas email list command returns recent inbox messages with their IDs, and nylas email search narrows by sender or subject. Each ID is a stable handle you pass straight into read. Listing 10 messages takes well under a second.

# Find a message ID, then dump its headers
nylas email search "*" --from "alerts@example.com" --json
nylas email read "$MSG_ID" --headers

For a forensic copy, the --mime flag returns the untouched RFC822 message. Save it to a file so you can re-parse it offline or attach it to a ticket without re-fetching. The raw source preserves multi-line headers exactly as the sending server wrote them.

# Save the raw RFC822 source for offline analysis
nylas email read "$MSG_ID" --mime > message.eml

How do I read the Received chain to trace delivery?

The Received headers form a stack: each relay prepends its own line, so the topmost is the last server to handle the message and the bottommost is the first. Read them bottom-up to follow the path from origin to inbox. Per RFC 5321 section 4.4, each line records the sending host, the receiving host, and a timestamp.

Comparing adjacent timestamps tells you where a message stalled. A normal hop completes in under a second; a gap of several minutes points at a greylisting delay or a backed-up queue. Extracting just the Received lines with grep isolates the route from the surrounding noise so you can scan five hops at a glance instead of forty header lines.

# Isolate the delivery path; read bottom line (origin) upward
nylas email read "$MSG_ID" --headers | grep -i "^Received:"

How do I check SPF, DKIM, and DMARC results?

The receiving server records every authentication verdict in one place: the Authentication-Results header, defined by RFC 8601. It carries a token for each mechanism — spf=pass, dkim=pass, and dmarc=pass — so one line tells you whether the message is authenticated.

SPF (RFC 7208) checks the sending IP against the domain's published senders. DKIM (RFC 6376) verifies a cryptographic signature over the message. DMARC (RFC 7489) ties those results to the visible From domain. A 2024 message that shows dmarc=pass aligned its authenticated identity with the address you see.

# Pull only the authentication verdicts
nylas email read "$MSG_ID" --headers | grep -i "Authentication-Results"

How do I spot a spoofed message in the headers?

A spoofed message reveals itself when the authenticated identity and the visible identity disagree. The clearest signal is a dmarc=fail or spf=fail verdict paired with a From address from a trusted brand. A second tell is a Return-Path domain that differs from the From domain.

The FBI's 2023 Internet Crime Report attributed 2.9 billion dollars in losses to business email compromise, much of it riding on forged From headers that pass a glance but fail authentication. Pulling From, Return-Path, and the DMARC verdict together turns a five-minute manual review into a one-line check you can script across a whole folder. For the protocol details behind each verdict, see SPF, DKIM, and DMARC explained.

# Compare the visible From with the envelope Return-Path and DMARC verdict
nylas email read "$MSG_ID" --headers | grep -iE "^(From|Return-Path):|dmarc="

Next steps

• SPF, DKIM, and DMARC explained — how each authentication mechanism produces the verdicts you just read
• Debug email delivery from the CLI — use the Received chain and headers to find where mail stalls
• Debug invisible characters in email — inspect the raw MIME source for hidden bytes that break parsing
• Turn emails into GitHub issues — pipe parsed message data into an issue tracker from the terminal
• Load email into Snowflake — archive headers and metadata for analysis at scale
• Command reference — every flag, subcommand, and example
• RFC 8601: Authentication-Results header — the spec defining the SPF, DKIM, and DMARC result tokens
• RFC 5321: SMTP and the Received header — how each relay stamps the delivery path
• Gmail API documentation — how Gmail exposes message headers and metadata