email threading headers explained: Message-ID, In-Reply-To, and References

Your agent sent a reply. The recipient saw it as a brand-new email, sitting alone in their inbox with zero context. No thread, no conversation history, just a standalone message that made the whole interaction look broken.

The problem was three missing headers. Email threading relies on three RFC 5322 headers working together: Message-ID uniquely identifies each email, In-Reply-To points to the direct parent message, and References stores the full ancestor chain of the thread. When all three are present and correct, email clients reconstruct conversations into coherent threads. When any of them are missing or malformed, threads fall apart.

That table covers the basics. Here's how each header actually works, how major email clients interpret them differently, and what this means when your agent (or your application) is sending email programmatically.

What Message-ID does#

Every outgoing email gets a Message-ID header. It's a globally unique identifier generated by the sending mail server at the moment of dispatch. The format defined in RFC 5322 is a local part, an @ symbol, and a domain. In the raw email source, it looks like this:

Message-ID: <abc123.456789@mail.example.com>

The sending server is responsible for generating this value. If you're sending through a transactional email API (Postmark, Mailgun, LobsterMail), the service generates it for you unless you explicitly provide one. The only hard rule: it must be globally unique. Two messages sharing the same Message-ID will confuse threading in unpredictable ways.

Most implementations combine a timestamp, a random string, and the sending domain to guarantee uniqueness. Something like 1712188800.a7f3b2c1d4e5@mail.yourapp.com is typical. The domain portion should match your actual sending domain. A mismatched domain in Message-IDs can trigger spam filters, since it looks like the sender is trying to obscure the origin.

In-Reply-To points to the parent#

When you reply to a message, your email client (or sending API) sets the In-Reply-To header to the Message-ID of the message being replied to. One value, pointing to one parent.

In-Reply-To: <abc123.456789@mail.example.com>

This is how email clients know a message is a reply and not a new thread. If you're building automated email workflows, setting In-Reply-To correctly is the single most important thing you can do for threading. Without it, every outbound message starts a fresh conversation in the recipient's inbox.

References holds the full thread history#

The References header contains a space-separated list of Message-IDs representing the entire ancestor chain of the conversation. The first ID is the original message that started the thread. The last ID is the message being directly replied to (same value as In-Reply-To).

References: <original@example.com> <reply1@example.com> <reply2@example.com>

As a thread grows, References accumulates every Message-ID from the conversation. RFC 5322 recommends keeping the full list but doesn't impose a hard size limit. In practice, some servers truncate it beyond a few kilobytes, though most threads never get that long.

The difference between In-Reply-To and References comes down to scope. In-Reply-To points to one parent. References maps the full lineage. Both matter: In-Reply-To lets a client build parent-child relationships, while References lets it reconstruct the entire conversation tree even when some messages are missing from the local mailbox.

How Gmail, Outlook, and Apple Mail thread differently#

Here's where the theory meets reality. Each email client has its own threading logic, and they don't all agree.

Gmail groups messages primarily by subject line matching. If two emails share the same subject (after stripping Re: and Fwd: prefixes), Gmail threads them together, even without matching In-Reply-To or References headers. This means Gmail will sometimes merge unrelated messages that happen to share a subject. It also means changing the subject line in a reply will split the thread, even if the References header is perfect.

Outlook takes the opposite approach. It relies on In-Reply-To and References for thread membership and falls back to Thread-Index and Thread-Topic (proprietary Exchange headers) for messages between Outlook systems. Subject matching is a last resort. This explains why a reply might thread correctly in Outlook but show up as a separate conversation in Gmail, or the other way around.

Apple Mail follows the RFC most closely. It uses In-Reply-To and References as the primary threading mechanism and only falls back to subject matching when headers are entirely absent.

The practical takeaway: if you want threads to work across all three, set all the headers and keep the subject line consistent. Belt and suspenders.

Threading in agent and programmatic email workflows#

Most threading guides assume a human is clicking "Reply" in a mail client, where the client handles headers automatically. When an AI agent sends email programmatically, nothing is automatic. Your code is responsible for storing Message-IDs and setting the right headers on every outbound message.

Here's what a properly threaded programmatic reply looks like:

// Agent receives an email and replies in-thread
const received = await inbox.receive();
const original = received[0];

await inbox.send({
  to: original.from,
  subject: `Re: ${original.subject}`,
  text: "Thanks for reaching out. Here's the information you requested...",
  inReplyTo: original.messageId,
  references: [
    ...(original.references || []),
    original.messageId
  ]
});

Three things to get right:

1. Store the Message-ID from every received email. You'll need it when the agent replies.
2. Set In-Reply-To to the Message-ID of the specific message being replied to.
3. Build References by taking the References array from the received message and appending its Message-ID to the end.

If your agent is scheduling meetings over email, threading keeps the back-and-forth coherent. Without it, each agent message lands as a separate conversation in the recipient's inbox. That's confusing for the human on the other end and makes the whole interaction feel disjointed.

This gets more complex in multi-agent email workflows where multiple agents participate in the same thread. Each agent needs access to the thread's References chain. If Agent A starts a conversation and Agent B needs to continue it, B needs the Message-IDs from A's exchange. Shared state or a message broker between agents solves this, but you have to design for it up front.

Debugging broken threads#

When threading breaks, diagnosis follows a predictable path.

Start by checking for Message-ID presence. Open the raw email source (in Gmail: "Show original"; in Outlook: "View message source"). Every message in the thread should have a unique Message-ID header. If it's missing, the sending server is misconfigured.

Next, verify In-Reply-To. The reply should contain an In-Reply-To header that matches the parent's Message-ID character for character. A common bug in programmatic senders is stripping the angle brackets or injecting extra whitespace around the value.

Then inspect References. The header should contain a growing list of Message-IDs. If it's empty or only contains the most recent parent, threading works for direct replies but breaks for deeper conversation trees.

Compare subject lines too. If headers look correct but Gmail still breaks the thread, the subject probably changed somewhere. Gmail's subject-based grouping can override header-based logic in both directions: a changed subject splits a thread, a matching subject can merge unrelated messages.

Finally, check for client-specific headers. If threading works in Gmail but breaks in Outlook, look for missing Thread-Index or Thread-Topic headers. Outlook uses these for its own threading logic, and messages from non-Exchange systems won't include them by default.

A quick way to pull the relevant headers from a raw email file:

grep -E '^(Message-ID|In-Reply-To|References|Thread-Index|Subject):' raw-email.eml

Generating unique Message-IDs at scale#

If you're sending thousands of emails per day, Message-ID uniqueness becomes a real engineering concern. The standard format is a local part, an @ symbol, and your sending domain. Common approaches:

• UUID v4 + domain: 550e8400-e29b-41d4-a716-446655440000@mail.yourapp.com
• Timestamp + random bytes + domain: 1712188800.a7f3b2c1d4@mail.yourapp.com
• Sequential counter + process ID + domain (works with a single sender process, risky otherwise)

If two messages accidentally share a Message-ID (from a bug, clock skew, or weak randomness), different clients handle it differently. Some merge the messages, displaying one and hiding the other. Some refuse to download the "duplicate." There's no recovery path once it happens. Prevention through strong random components is the only real strategy.

Threading is one of those things that works invisibly when set up right and fails loudly when it's not. Store your Message-IDs, set In-Reply-To and References on every reply, keep subject lines consistent, and your threads will hold together across every major email client. If your agent needs its own inbox with threading headers handled automatically, LobsterMail takes care of that out of the box.