Threads

What is a Thread?

A Thread is an API resource that represents a single conversation. It acts as a container, grouping a series of related Messages together in chronological order, just like a conversation thread in a traditional email client.

Threads are created automatically. When your agent sends a Message that isn’t a reply to a previous one, a new Thread is initiated. Any subsequent replies are automatically added to this same Thread, allowing your agent to easily maintain the context of a conversation over time.

Querying Threads

While Threads are created implicitly, you can retrieve them in two powerful ways: scoped to a single Inbox or across your entire Organization.

Listing Threads per Inbox

This is the standard way to retrieve all the conversations associated with a single agent or Inbox.

1
# You'll need an inbox ID to list threads from.
2
inbox_id = "inbound-agent@agentmail.to"
3
4
# This retrieves all threads within the specified Inbox
5
6
inbox_threads = client.inboxes.threads.list(inbox_id=inbox_id)

Listing Threads Across an Organization

This is one of AgentMail’s most powerful features. By omitting the inbox_id, you can retrieve a list of Threads from every Inbox in your Organization. This org-wide querying capability is essential for building:

• Supervisor Agents: An agent that monitors conversations from a fleet of other agents.
• Analytics Dashboards: Building something where you need visibility across all inboxes across the organization
• Advanced Workflows: Systems that can route or escalate conversations between different agents with different permissions.

1
# By not providing an inbox_id, we get all threads in the organization
2
all_threads = client.threads.list()
3
4
print(f"Found {len(all_threads)} threads across the entire organization.")

Getting a Single Thread

You can also retrieve a single Thread by its ID. This will return the Thread object, which typically contains a list of all its associated Messages and their ID’s. A common workflow is listing the messages in a thread and calling the messages.reply method on the last one.

1
thread_id = "thread_456def"
2
3
# This retrieves a single thread and its messages
4
5
thread = client.threads.get(
6
thread_id="thread_id"
7
)
8
9
print(f"Retrieved thread {thread.id} with {len(thread.messages)} messages.")