Threads

A thread is a group of related messages forming a conversation. AgentPost creates and manages threads automatically based on email headers -- you never need to manually group messages.

Key properties

How threading works

AgentPost uses the standard email threading mechanism defined in RFC 5322:

1. When a reply is sent or received, the In-Reply-To header references the original message's Message-ID
2. The References header contains the chain of all prior Message-IDs
3. AgentPost matches these headers to find the existing thread

Message 1 (Message-ID: abc@example.com)     --> Thread created
  |
  +-- Message 2 (In-Reply-To: abc@example.com) --> Added to thread
       |
       +-- Message 3 (In-Reply-To: def@example.com,
                       References: abc@example.com, def@example.com)
                                                    --> Added to same thread

Listing threads

// List threads for an inbox
const threads = await client.threads.list('inb_abc123', {
  limit: 20,
});

for (const thread of threads.data) {
  console.log(`${thread.subject} (${thread.message_count} messages)`);
  console.log(`  Last activity: ${thread.last_message_at}`);
}

threads = client.threads.list(
    inbox_id="inb_abc123",
    limit=20,
)

for thread in threads.data:
    print(f"{thread.subject} ({thread.message_count} messages)")
    print(f"  Last activity: {thread.last_message_at}")

curl "https://api.agent-post.dev/api/v1/inboxes/inb_abc123/threads?limit=20" \
  -H "Authorization: Bearer $AGENTPOST_API_KEY"

Getting a thread with messages

// Get thread details
const thread = await client.threads.get('thr_ghi789');

console.log(`Thread: ${thread.subject}`);
console.log(`Messages: ${thread.message_count}`);
console.log(`Participants: ${thread.participants.map(p => p.email).join(', ')}`);

thread = client.threads.get("thr_ghi789")

print(f"Thread: {thread.subject}")
print(f"Messages: {thread.message_count}")
print(f"Participants: {', '.join(p['email'] for p in thread.participants)}")

curl "https://api.agent-post.dev/api/v1/threads/thr_ghi789" \
  -H "Authorization: Bearer $AGENTPOST_API_KEY"

Thread lifecycle

1. Created -- A new thread is created when the first outbound message is sent or the first inbound message arrives
2. Active -- New messages (replies) are added to the thread automatically
3. Forwarded -- When a message is forwarded, a new thread is created for the forwarded conversation

Threads are never manually created or deleted. They exist as long as their messages exist.

Message ordering

Messages within a thread are ordered by created_at timestamp. The first message is the conversation starter, and subsequent messages are replies.

Cross-inbox threads

A thread belongs to a single inbox. If the same conversation involves multiple inboxes (e.g., a message forwarded from one inbox to another), each inbox maintains its own thread. The forwarded message creates a new thread in the target inbox.

Labels on threads

Thread labels are separate from message labels. You can label a thread to categorize the entire conversation, independent of individual message labels.

// Add labels to a thread
await client.threads.addLabels('thr_ghi789', {
  labels: ['escalated', 'priority-high'],
});

// List threads by label
const escalated = await client.threads.list('inb_abc123', {
  label: 'escalated',
});

# Add labels to a thread
client.threads.add_labels(
    thread_id="thr_ghi789",
    labels=["escalated", "priority-high"],
)

# List threads by label
escalated = client.threads.list(
    inbox_id="inb_abc123",
    label="escalated",
)

# Add labels to a thread
curl -X POST https://api.agent-post.dev/api/v1/threads/thr_ghi789/labels \
  -H "Authorization: Bearer $AGENTPOST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"labels": ["escalated", "priority-high"]}'

Relationships

• A thread belongs to one inbox
• A thread contains one or more messages ordered chronologically
• A thread can have labels for categorization
• Threads are scoped to an environment via their inbox

Tips

• Use threads to track full conversations rather than individual messages
• Thread message_count is a quick indicator of conversation depth
• last_message_at is useful for sorting conversations by recency
• Forwarding always creates a new thread -- it does not add to the original
• Labels on threads are independent of labels on their messages