Conversation Threads

LobsterMail automatically groups related emails into threads using standard email headers (In-Reply-To, References) and subject line matching. Threads make it easy for agents to follow multi-message conversations without manual correlation.

How Threading Works#

When an email arrives, LobsterMail resolves its thread using this algorithm:

1. In-Reply-To header -- If the email has an In-Reply-To header pointing to a known message in the same inbox, it joins that thread.
2. References chain -- If no direct reply match, walk the References header (last to first) looking for a match.
3. Subject fallback -- Normalize the subject (strip Re:, Fwd:, FW:, AW:, etc.) and match against recent threads (last 7 days) in the same inbox.
4. New thread -- If no match is found, a new thread is created.

Threads are scoped per-inbox for clean access control.

Listing Threads#

GET /v1/inboxes/{inboxId}/threads?limit=20&cursor=...

Returns threads ordered by most recent activity:

{
  "data": [
    {
      "id": "thd_abc123",
      "inboxId": "ibx_xyz",
      "subject": "Invoice #1234",
      "emailCount": 3,
      "lastEmailAt": "2026-03-11T10:30:00.000Z",
      "createdAt": "2026-03-10T09:00:00.000Z"
    }
  ],
  "hasMore": false,
  "cursor": null
}

SDK#

const { data: threads } = await inbox.listThreads({ limit: 10 });
for (const thread of threads) {
  console.log(`${thread.subject} (${thread.emailCount} emails)`);
}

Viewing a Thread#

GET /v1/inboxes/{inboxId}/threads/{threadId}

Returns the thread with all emails in chronological order:

{
  "id": "thd_abc123",
  "subject": "Invoice #1234",
  "emailCount": 3,
  "emails": [
    { "id": "eml_1", "from": "billing@example.com", "subject": "Invoice #1234", ... },
    { "id": "eml_2", "from": "bot@lobstermail.ai", "subject": "Re: Invoice #1234", ... },
    { "id": "eml_3", "from": "billing@example.com", "subject": "Re: Invoice #1234", ... }
  ]
}

SDK#

const thread = await inbox.getThread('thd_abc123');
for (const email of thread.emails) {
  console.log(`${email.from}: ${email.subject}`);
}

Replying Within a Thread#

When sending a reply, include the inReplyTo field with the Message-ID of the email you're replying to. LobsterMail will automatically set the In-Reply-To and References MIME headers and associate the outgoing email with the correct thread.

const result = await inbox.send({
  to: ['billing@example.com'],
  subject: 'Re: Invoice #1234',
  body: { text: 'Please send the updated invoice.' },
  inReplyTo: '<original-message-id@example.com>',
});

REST API#

POST /v1/emails/send
{
  "from": "bot@lobstermail.ai",
  "to": ["billing@example.com"],
  "subject": "Re: Invoice #1234",
  "body": { "text": "Please send the updated invoice." },
  "inReplyTo": "<original-message-id@example.com>"
}

Thread ID on Emails#

Every email includes a threadId field in its response. You can use this to check which thread an email belongs to without calling the threads endpoint:

const emails = await inbox.receive();
for (const email of emails) {
  console.log(`${email.subject} -- thread: ${email.threadId}`);
}

Existing emails created before threading was enabled will have threadId: null.

MCP Tools#

Two MCP tools are available for working with threads:

• list_threads -- List conversation threads for an inbox
• get_thread -- Get a full thread with all emails

The send_email tool accepts an optional in_reply_to parameter for threading replies.