An AI agent sends an email, a reply lands three hours later, and the agent has to answer two questions before it can do anything useful: which conversation is this, and what did I last say? Get the first one wrong and the agent's reply shows up in the recipient's inbox as a brand-new message instead of slotting into the existing thread. To the person on the other end, that looks broken — like the agent forgot the conversation it started.
Threading is the part of agent email that's easy to get almost right and quietly wrong. The fix lives in a few email headers most developers never touch, and in the for the terminal. I work on the CLI, so the terminal commands below are the ones I reach for when I'm testing a reply loop.
The three headers that make threading work
Threading runs on three email headers, not on subject lines. Every message carries a Message-ID — a globally unique identifier the sending server stamps on it. When someone replies, their mail client adds In-Reply-To (the Message-ID of the message being answered) and References (the full chain of Message-ID values, oldest to newest). Those two headers are how every mail client decides which messages belong together.
Here's what the chain looks like across one exchange. The agent's first message gets a Message-ID; the reply points back at it; the agent's follow-up references both:
# The agent's outbound message
Message-ID: <[email protected]>
Subject: Following up on your demo request
# The recipient's reply
Message-ID: <[email protected]>
In-Reply-To: <[email protected]>
References: <[email protected]>
Subject: Re: Following up on your demo request
# The agent's follow-up
Message-ID: <[email protected]>
In-Reply-To: <[email protected]>
References: <[email protected]> <[email protected]>
The References header grows with every message. By the time a thread is five messages deep, it carries five Message-ID values in order — a complete audit trail of the conversation that Gmail, Outlook, Apple Mail, and Thunderbird all read the same way.
Why subject-line matching breaks
Matching replies by subject line is the trap most agent implementations fall into: if a subject starts with Re: and contains the original text, treat it as a reply. It works in testing and fails in production, for three concrete reasons. Subject matching has no way to tell two conversations apart when they share a subject, and no way to follow one when the subject changes.
Recipients edit subjects. A reply to "Q3 budget review" comes back as "Re: Q3 budget review — updated numbers attached", and a naive contains-match still works, until the edit drops the original words entirely.
Multiple threads share a subject. Two prospects both get "Following up on your demo request". A reply to either one matches both, and the agent can't tell which prospect answered.
Forwards reuse the subject. Someone forwards the thread to a colleague who replies. The subject is unchanged but the conversation context is completely different.
The header approach has none of these failure modes because In-Reply-To and References point at specific Message-ID values, not human-readable text. Match on headers first and fall back to subject only when headers are missing, which is rare enough to treat as a broken-client edge case.
How Nylas preserves threading
Nylas keeps the threading chain intact however a message moves through the mailbox, which means your agent never has to generate a Message-ID or hand-assemble a References header. Threading holds on both outbound paths and on inbound mail alike.
API sends (POST /v3/grants/{grant_id}/messages/send): passreply_to_message_idand Nylas fetches the original'sMessage-ID, then setsIn-Reply-ToandReferenceson the outbound message automatically. Sending an existing draft behaves the same way, since a draft send runs through the same path.
SMTP submission (port 465 or 587): if a human replies from a mail client connected over SMTP, Nylas preserves theMessage-ID,In-Reply-To, andReferencesthe client set.
Inbound messages: when a reply arrives, Nylas stores the full headers. Read them withfields=include_headersfor the complete set, orfields=include_basic_headersto skip the full header payload — which is often larger than the message body itself — and get justMessage-ID,In-Reply-To, andReferences.
That consistency is the reason an agent can send via the API and have a human follow up via IMAP without the thread splitting apart. Both paths write to the same mailbox and share the same header chain.
List and fetch threads with the Threads API
Rather than parse In-Reply-To and References yourself, ask the webhook, the payload includes a thread_id you look up here to pull the full history before responding.
There's one more reason to fetch the thread rather than rely on the webhook payload alone. When a message body exceeds about 1 MB, the trigger name becomes message.created.truncated and the body is omitted to keep the payload small. In that case the agent has the thread_id and message_id but not the text, so a follow-up GET /messages/{message_id} returns the full body it needs to reply. Fetching the thread gives you the conversation's message summaries and IDs; the full body of any single message comes from the messages endpoint.
From an SDK, fetching the thread and its messages is a couple of calls. This is the pattern I use after a webhook fires — get the thread, then reconstruct what was said:
// After receiving a message.created webhook:
const thread = await nylas.threads.find({
identifier: AGENT_GRANT_ID,
threadId: message.thread_id,
});
// thread.data.messageIds has the full conversation chain.
const messages = await Promise.all(
thread.data.messageIds.map((id) =>
nylas.messages.find({ identifier: AGENT_GRANT_ID, messageId: id }),
),
);
Reply in-thread from the API and CLI
A reply that threads correctly is a normal send with one extra field: reply_to_message_id, set to the message you're answering. Nylas reads that ID, pulls the original's Message-ID, and stamps In-Reply-To and References on the outbound message so it lands in the right thread in every recipient's client — and in the agent's own mailbox. From the API:
curl --request POST \
--url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/messages/send" \
--header "Authorization: Bearer <NYLAS_API_KEY>" \
--header "Content-Type: application/json" \
--data '{
"reply_to_message_id": "<MESSAGE_ID>",
"to": [{ "email": "[email protected]" }],
"subject": "Re: Following up on your demo request",
"body": "Thanks for getting back to me, Alice. Here are the next steps..."
}'
The CLI does the same with one flag. — the full protocol-level explanation
— the
reply_to_message_id field and other send options— the
--reply-to flag and other send options
SOCIAL SHARE CARD GENERATOR