会话

会话将相关消息分组为对话。AgentSend 基于标准邮件头部自动组织会话线程，使您的智能体始终拥有完整的对话上下文。

概述

AgentSend 中的每个邮件对话都组织在一个会话中。 A thread collects all related messages — the original email, every reply, and every reply-to-reply — into a single, ordered conversation object. This makes it easy for agents to read the full history before composing a response.

会话是自动创建的。 When AgentSend receives or sends a message that starts a new conversation, a thread is created. When a reply arrives, AgentSend matches it to the existing thread and appends the new message.

会话线程工作原理

AgentSend follows the standard email threading model used by every major email client. When a reply arrives, AgentSend inspects the In-Reply-To and References headers to identify which existing thread the message belongs to. If a match is found, the message is appended to that thread. If no match is found, a new thread is created.

You can also explicitly associate a message with a thread by including the threadId field when sending. This is useful when you are initiating a follow-up from your agent's side and want to keep it grouped with a prior conversation, even if the recipient starts a fresh reply chain.

匹配算法

1. Check the In-Reply-To header against all known message IDs in the inbox.
2. If no match, scan the References header list from right (most recent) to left.
3. If still no match, create a new thread for this message.

会话属性

每个会话对象都有以下字段：

列出会话

Retrieve all threads for an inbox using a GET request. Results are ordered by lastMessageAt descending so the most active conversations appear first.

// GET /inboxes/{id}/threads?limit=20&offset=0
const res = await fetch(
  `https://api.agentsend.io/inboxes/${inboxId}/threads?limit=20&offset=0`,
  { headers: { "x-api-key": process.env.AGENTSEND_API_KEY } }
);

const { data, total } = await res.json();

for (const thread of data) {
  console.log(thread.id, thread.subject, thread.messageCount);
}

查询参数

获取会话消息

Fetch every message in a thread in chronological order. This gives your agent the complete conversation history it needs to compose a contextually aware reply.

// GET /threads/{id}/messages
const res = await fetch(
  `https://api.agentsend.io/threads/${threadId}/messages`,
  { headers: { "x-api-key": process.env.AGENTSEND_API_KEY } }
);

const { data } = await res.json();

// Build a conversation history for your LLM
const history = data.map(msg => ({
  role: msg.direction === "outbound" ? "assistant" : "user",
  content: msg.bodyText,
}));

console.log(`Loaded ${history.length} messages from thread`);

在会话中回复

To continue an existing conversation, include the threadId when sending a message. AgentSend will automatically set the correct In-Reply-To and References headers so the reply appears in the recipient's email client as part of the same conversation.

// POST /inboxes/{id}/messages — reply within an existing thread
await fetch(`https://api.agentsend.io/inboxes/${inboxId}/messages`, {
  method: "POST",
  headers: {
    "x-api-key": process.env.AGENTSEND_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    to: ["customer@example.com"],
    subject: "Re: Your support request",
    bodyText: "Thanks for reaching out! Here is the information you requested...",
    threadId: "thrd_abc123", // ties this message to the existing conversation
  }),
});

使用场景

会话解锁了需要跨多次邮件交换保持记忆的一系列工作流。

• 客户支持 — Load the full thread before generating a reply so your support agent has all prior context. Assign threads to human agents only when needed.
• 销售跟进 — Track multi-touch outreach sequences. Know when a prospect last replied and how many messages are in a chain before escalating.
• 日程安排与协调 — Run back-and-forth negotiations (meeting times, contract terms) inside a single thread so the conversation history is always accessible.
• 研究收集 — Send an initial query, collect responses, and follow up with clarifying questions — all within one organized thread per contact.