---
type: ADR
id: "0001"
title: "IMAP thread resolution prefers In-Reply-To and falls back to References"
status: active
date: 2026-04-28
---

## Context

The IMAP ingress flow stores a `thread_id` before dispatching work to OpenClaw. Previously the bridge only used `In-Reply-To` to find a parent task. Some valid email clients preserve thread ancestry through `References` even when `In-Reply-To` is absent. In those cases, the bridge created a new `thread_id`, which broke conversation continuity and downstream session reuse.

This decision needs to be durable because future refactors of mail parsing, dispatch, or storage must preserve the same thread-resolution behavior.

## Decision

The bridge resolves parent thread linkage by trying `In-Reply-To` first. If no parent task is found, it falls back to `References`, scanning message IDs from last to first and using the first match found in the database. If neither header yields a known parent, the message's own `message_id` becomes the new `thread_id`.

## Options considered

- **Use `In-Reply-To` first, then `References` last-to-first** (chosen): preserves existing behavior, matches common email ancestry ordering, and favors the most recent known parent.
- **Use only `In-Reply-To`**: simpler, but breaks valid threads when clients omit `In-Reply-To`.
- **Search `References` from first to last**: may attach to an older ancestor even when a more recent known parent exists.
- **Normalize all thread linkage into a more complex conversation graph**: more flexible, but out of scope for the current bridge behavior.

## Consequences

Thread continuity is improved for replies that rely on `References`.
Future contributors have an explicit behavioral contract for threading semantics.
Mail parsing changes must preserve the header precedence and reverse scan behavior unless a new ADR supersedes this one.
The current approach still depends on existing message IDs being present in the database; if upstream behavior changes significantly, this decision may need reevaluation.

## Advice

If a future change wants different precedence rules or deeper conversation reconstruction, create a new ADR rather than silently changing this behavior.