스레드

스레드는 관련 메시지를 대화로 그룹화합니다. AgentSend는 표준 이메일 헤더를 기반으로 자동으로 메시지를 스레드화하여 에이전트가 항상 전체 대화 맥락을 가질 수 있게 합니다.

개요

AgentSend의 모든 이메일 대화는 스레드로 구성됩니다. 스레드는 관련된 모든 메시지(원본 이메일, 모든 답장, 답장에 대한 답장)를 하나의 정렬된 대화 객체로 수집합니다. 덕분에 에이전트는 답장을 작성하기 전에 전체 기록을 쉽게 읽을 수 있습니다.

스레드는 자동으로 생성됩니다. AgentSend가 새로운 대화를 시작하는 메시지를 수신하거나 보내면 스레드가 생성됩니다. 답장이 도착하면 AgentSend가 기존 스레드와 일치시켜 새 메시지를 추가합니다.

ℹ

스레드는 수신함 범위로 제한됩니다. 두 개의 다른 수신함이 받은 동일한 이메일 체인은 두 개의 별도 스레드 객체를 생성합니다.

스레딩 작동 방식

AgentSend는 모든 주요 이메일 클라이언트가 사용하는 표준 이메일 스레딩 모델을 따릅니다. 답장이 도착하면 AgentSend는 In-Reply-To와 References 헤더를 검사하여 메시지가 어떤 기존 스레드에 속하는지 확인합니다. 일치하는 항목이 있으면 해당 스레드에 추가되고, 없으면 새 스레드가 생성됩니다.

보낼 때 threadId 필드를 포함해 메시지를 스레드에 명시적으로 연결할 수도 있습니다. 에이전트 측에서 후속 메시지를 시작하면서 이전 대화와 함께 그룹화하고 싶을 때 유용합니다. 수신자가 새 답장 체인을 시작하더라도 말입니다.

💡

수신 웹훅 페이로드에서 항상 threadId를 읽고 답장할 때 다시 전달하세요. 수신자가 제목을 변경해도 정확한 그룹화를 보장합니다.

매칭 알고리즘

수신함의 모든 알려진 메시지 ID와 In-Reply-To 헤더를 대조합니다.
일치 항목이 없으면 References 헤더 목록을 오른쪽(가장 최근)부터 왼쪽으로 스캔합니다.
여전히 일치 항목이 없으면 이 메시지를 위한 새 스레드를 생성합니다.

스레드 속성

각 스레드 객체는 다음 필드를 갖습니다:

속성	타입	설명
`id`	string	스레드의 고유 식별자.
`inboxId`	string	이 스레드가 속한 수신함.
`subject`	string	스레드의 첫 메시지 제목.
`messageCount`	integer	이 스레드의 총 메시지 수.
`lastMessageAt`	string (ISO 8601)	가장 최근 메시지의 시각.
`createdAt`	string (ISO 8601)	스레드가 처음 생성된 시각.

스레드 목록 조회

GET 요청으로 수신함의 모든 스레드를 가져옵니다. 결과는 lastMessageAt 내림차순으로 정렬되어 가장 활발한 대화가 먼저 표시됩니다.

javascript

// 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);
}

쿼리 파라미터

파라미터	타입	기본값	설명
`limit`	integer	20	반환할 최대 스레드 수. 최대 100.
`offset`	integer	0	페이지네이션을 위해 건너뛸 스레드 수.

스레드 메시지 가져오기

스레드의 모든 메시지를 시간순으로 가져옵니다. 이를 통해 에이전트는 맥락을 인지한 답장을 작성하는 데 필요한 완전한 대화 기록을 얻을 수 있습니다.

javascript

// 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`);

ℹ

스레드 내의 메시지는 시간 오름차순(sentAt 오래된 것부터)으로 반환됩니다. 이는 대부분의 LLM 대화 API에서 예상하는 자연스러운 순서와 일치합니다.

스레드 내 답장하기

기존 대화를 계속하려면 메시지를 보낼 때 threadId를 포함하세요. AgentSend는 자동으로 올바른 In-Reply-To와 References 헤더를 설정하여 수신자의 이메일 클라이언트에 답장이 동일한 대화의 일부로 표시되도록 합니다.

javascript

// 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
  }),
});

⚠

threadId를 생략하면 동일한 제목을 사용하더라도 발신 메시지가 새 스레드를 시작합니다. 대화를 계속할 때는 항상 threadId를 전달하세요.

사용 사례

스레드는 여러 이메일 교환에 걸쳐 메모리가 필요한 워크플로 집합을 활성화합니다.

고객 지원 — 답장을 생성하기 전에 전체 스레드를 로드하여 지원 에이전트가 모든 이전 컨텍스트를 갖도록 합니다. 필요할 때만 스레드를 사람 상담원에게 할당하세요.
영업 후속 조치 — 멀티 터치 아웃리치 시퀀스를 추적합니다. 잠재 고객이 마지막으로 답장한 시기와 체인에 몇 개의 메시지가 있는지 확인한 후 에스컬레이션하세요.
일정 조정 — 미팅 시간, 계약 조건 등의 반복적인 협상을 단일 스레드 내에서 진행하여 대화 기록에 항상 접근할 수 있도록 합니다.
리서치 수집 — 초기 질의를 보내고 응답을 수집하고 명확한 질문으로 후속 조치를 취합니다. 모두 연락처별로 체계적으로 구성된 하나의 스레드 내에서 처리합니다.

← 이전 메시지 다음 → 웹훅