Email Threading

mails-agent automatically groups related emails into threads, so your agent can follow entire conversations without manual tracking.

How Threading Works

When an email arrives, mails-agent resolves its thread using the In-Reply-To and References headers only. There is no subject-line fallback.

Header-based resolution

The In-Reply-To and References headers are the standard mechanism defined by RFC 2822. When an incoming email contains these headers, mails-agent looks up the referenced Message-ID values and assigns the email to the matching thread.

API Endpoints

GET/v1/threads — List all threads

Returns a paginated list of threads for the authenticated mailbox, ordered by most recent activity.

Query parameters

ParameterTypeDescription
limitnumberMax threads to return (default 20, max 100)
offsetnumberPagination offset (default 0)

Example

curl -s -H "Authorization: Bearer $API_KEY" \
  "https://mails-worker.genedai.workers.dev/v1/threads?limit=10"
{
  "threads": [
    {
      "thread_id": "thr_abc123",
      "latest_email_id": "msg_005",
      "from_address": "[email protected]",
      "from_name": "Alice",
      "subject": "Partnership proposal",
      "received_at": "2026-04-01T12:30:00Z",
      "message_count": 5,
      "has_attachments": false
    }
  ]
}
GET/v1/thread?id=thr_abc123 — Get a single thread

Returns the full thread including all messages, ordered chronologically.

Query parameters

ParameterTypeDescription
idstringThread ID (required)

Example

curl -s -H "Authorization: Bearer $API_KEY" \
  "https://mails-worker.genedai.workers.dev/v1/thread?id=thr_abc123"
{
  "thread_id": "thr_abc123",
  "emails": [
    {
      "id": "msg_001",
      "from_address": "[email protected]",
      "from_name": "Alice",
      "to_address": "[email protected]",
      "subject": "Partnership proposal",
      "body_text": "Hi, I'd like to discuss a partnership...",
      "received_at": "2026-03-28T10:00:00Z"
    },
    {
      "id": "msg_002",
      "from_address": "[email protected]",
      "from_name": "Agent",
      "to_address": "[email protected]",
      "subject": "Re: Partnership proposal",
      "body_text": "Thank you for reaching out...",
      "received_at": "2026-03-28T10:05:00Z"
    }
  ]
}

Sending Replies

To send a reply that is correctly threaded, include the in_reply_to field in your POST /v1/send request. mails-agent will automatically set the In-Reply-To and References headers on the outgoing email.

Example: Reply to a message

curl -s -X POST -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  "https://mails-worker.genedai.workers.dev/v1/send" \
  -d '{
    "from": "[email protected]",
    "to": ["[email protected]"],
    "subject": "Re: Partnership proposal",
    "text": "Thank you for reaching out. We would love to explore this further.",
    "in_reply_to": "msg_001"
  }'
{
  "id": "msg_003",
  "provider_id": "re_xyz789",
  "thread_id": "thr_abc123"
}

The in_reply_to field accepts either a mails-agent message ID (msg_xxx) or a raw RFC 2822 Message-ID value. When a mails-agent message ID is provided, the system resolves the original Message-ID header automatically.

Thread Behavior Notes