email header analysis for delivery debugging

Your agent sent a batch of outreach emails yesterday. Half never arrived. No bounce notification, no error message, just silence. The recipients' servers accepted the connections, queued the messages, and then nothing showed up in anyone's inbox.

This is where email headers come in. Every email carries a hidden block of metadata that records exactly what happened during delivery: which servers handled it, whether authentication passed, how long each hop took, and why a message might have been flagged or dropped. Learning to read these headers is the fastest way to diagnose delivery problems, and it beats refreshing the recipient's spam folder and hoping for the best.

What email headers actually contain#

Raw email headers look like gibberish the first time you see them. Dozens of lines of server names, timestamps, cryptographic hashes, and protocol codes crammed together with no obvious structure. But the useful information clusters into a few categories, and once you know what to look for, you can skim past the noise.

Received lines trace the message's path from sender to recipient. Each server that handles the message stamps its own Received line at the top of the header block. Because they're prepended rather than appended, you read them bottom-to-top to follow the chronological route. We'll come back to this.

The Authentication-Results field tells you whether SPF, DKIM, and DMARC checks passed. These three protocols form the backbone of email trust, and a failure in any of them can route your message to spam or get it rejected on the spot.

Return-Path shows where bounce notifications go. Message-ID is a unique identifier for that specific message. X-headers are custom fields added by servers along the route, often carrying spam scores, filtering decisions, and policy flags that the sending side never sees.

Here's a simplified version of what headers look like on a message that arrived successfully:

Received: from mail-relay.example.com (198.51.100.42)
    by mx.recipient.com with ESMTPS id abc123
    for <recipient@example.com>; Mon, 31 Mar 2026 14:22:08 -0400
Authentication-Results: mx.recipient.com;
    spf=pass (sender IP is 198.51.100.42) smtp.mailfrom=sender@example.com;
    dkim=pass header.d=example.com header.s=selector1;
    dmarc=pass (policy=reject) header.from=example.com
Return-Path: <sender@example.com>
Message-ID: <20260331182208.abc123@example.com>

Every field tells part of the story. The Received line shows the sending IP and receiving server. Authentication-Results confirms all three checks passed. Return-Path confirms the envelope sender matches the domain. When something goes wrong, one of these fields will show you exactly where.

Reading headers bottom to top#

The single most common mistake when debugging headers is reading them top to bottom. Since each server prepends its Received line, the newest entry sits at the top and the oldest at the bottom.

To trace an email's journey:

1. Scroll to the bottommost Received line. That's the originating server.
2. Read upward through each subsequent hop. Each Received line represents a handoff between servers.
3. Compare the timestamps between hops to spot delays.

A 45-second gap between two servers on the same internal network usually points to greylisting or a queue backlog. A message that reached the recipient's MX server in under a second but took 12 minutes to appear in the inbox was likely held for content scanning or reputation analysis.

These timing clues are invisible unless you read the headers. The sender's logs say "delivered." The recipient sees an empty inbox. The gap between those two realities is where headers tell you what actually happened.

The three authentication checks that matter#

Most delivery failures trace back to authentication. If you only learn to read three header fields, make it the results for SPF, DKIM, and DMARC.

SPF (Sender Policy Framework) verifies that the sending server's IP address is authorized to send mail for the domain in the From address. Your domain's DNS contains an SPF record listing allowed IPs. If the sending IP doesn't match that list, SPF fails.

In headers, you'll see results like spf=pass, spf=softfail (the IP wasn't listed but the domain uses the lenient ~all mechanism), spf=fail (the IP wasn't listed and the domain's policy says to reject), or spf=none (no SPF record exists at all).

DKIM (DomainKeys Identified Mail) attaches a cryptographic signature to the message body and selected headers. The recipient's server checks this signature against a public key published in DNS. If it verifies, the message wasn't tampered with in transit. A dkim=fail result usually means the message was altered after signing, or the signing key was rotated without updating the DNS record.

DMARC (Domain-based Message Authentication, Reporting, and Conformance) ties SPF and DKIM together. It checks whether at least one of them passes and aligns with the domain in the From header. DMARC also tells the recipient's server what to do with failures: none (just report it), quarantine (send to spam), or reject (drop it silently). A dmarc=fail with policy=reject means the message was killed, and the recipient's server was following the sender's own published instructions.

If you've hit a permanent rejection before, that DMARC reject is one of the common causes behind a 550 denied by policy error.

Patterns you'll find in failed deliveries#

After reading hundreds of email headers across different agent deployments, certain failure signatures keep repeating.

An SPF softfail paired with a missing DKIM signature is the most reliable recipe for the spam folder. The message isn't rejected outright, but Gmail, Outlook, and most corporate mail servers will bury it below promotional tabs or spam. The fix is straightforward: add the sending service's IP to your SPF record and enable DKIM signing. Both are DNS-level changes that take about five minutes to make and up to 48 hours to propagate.

DKIM failures after forwarding tell a different story. When a forwarding server modifies headers (which most do), the original DKIM signature breaks. This isn't misconfiguration on your end. ARC (Authenticated Received Chain) headers help receiving servers trust the forwarding chain by preserving the original authentication results, but ARC adoption is still uneven across providers.

Sometimes every authentication check passes and the message still gets filtered. When that happens, look at the X-headers. Fields like X-Spam-Status, X-MS-Exchange-Organization-SCL, or X-Policy-Verdict reveal content-based filtering decisions that override authentication entirely. Your message was trusted as genuinely coming from you. The recipient's server just didn't like what you said.

Long delays between internal hops are a subtler problem. If headers show a 30-second pause between two relays on the same provider, you're likely hitting a content scanner queue or a rate limiter. One slow hop is tolerable. Five slow hops across 500 messages means your emails trickle in over hours instead of arriving as a batch, which tanks open rates even when nothing technically bounced.

We covered more of these operational pitfalls in 5 agent email setup mistakes that tank your deliverability.

Tools that speed up header analysis#

You don't need to eyeball raw header text every time. Several tools parse the mess into readable reports.

MxToolbox Header Analyzer takes pasted raw headers and produces a visual breakdown of hops, delay timings, and authentication verdicts. It's the best option for quick one-off investigations.

Google Admin Toolbox Messageheader gives a clean delay visualization that makes it easy to spot exactly where a message stalled in transit.

Mailtrap lets you inspect headers on test emails in a sandboxed environment without risking real recipient inboxes. It's good for verifying your setup before going live.

For a single failed email, paste its headers into MxToolbox and you'll have an answer in seconds. For ongoing monitoring, configure DMARC aggregate reports (the rua tag in your DMARC DNS record) to receive daily summaries of authentication pass rates across all receiving servers.

Why this matters for agent email#

Agents don't get the "did you see my email?" follow-up from a confused human recipient. When an agent's emails land in spam or get silently rejected, nobody flags the problem. Delivery failures are invisible by default, and they compound quietly. An agent sending 200 emails with a 40% spam rate doesn't know it's wasting 80 messages per batch.

The first line of defense is getting authentication right before you ever need to debug a header. That means correctly configured SPF, DKIM, and DMARC records for whatever domain or service your agent sends from.

LobsterMail handles this automatically for every inbox. SPF, DKIM, and DMARC are pre-configured on @lobstermail.ai addresses, so every outbound message passes all three checks without any DNS setup on your end. If you want to send from a custom domain, LobsterMail generates the required DNS records and verifies them once you've added them.

If you'd rather skip the DNS configuration and start with pre-authenticated email, grab an inbox here and your agent can send its first email in under a minute.

But even with perfect authentication, recipient-side filtering can still catch you. Content scanning, IP reputation, and sending volume patterns all apply after authentication passes. When messages still don't arrive, the headers are your diagnostic tool.

Read bottom to top. Check authentication results first. Look at hop delays second. Inspect X-headers third. Most delivery problems reveal themselves within the first five minutes of opening the raw headers, and the fix is usually a single DNS record away.