Core Concepts

Threads

Organizing conversations across your Inboxes.

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.
2inbox_id = "inbound-agent@agentmail.to"
3
4# This retrieves all threads within the specified Inbox
5
6inbox_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
2all_threads = client.threads.list()
3
4print(f"Found {all_threads.count} threads across the entire organization.")
Coming Soon: Org-Wide Semantic Search

We are actively developing semantic search for the organization-wide thread listing endpoint. Soon, you’ll be able to find Threads based on the meaning and concepts within the Messages, not just keywords.

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.

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

Copy for Cursor / Claude

Copy one of the blocks below into Cursor or Claude for complete Threads API knowledge in one shot.

1"""
2AgentMail Threads — copy into Cursor/Claude.
3
4Setup: pip install agentmail python-dotenv. Set AGENTMAIL_API_KEY in .env.
5
6API reference:
7- inboxes.threads.list(inbox_id, limit?, page_token?, labels?, before?, after?, ascending?)
8- inboxes.threads.get(inbox_id, thread_id)
9- inboxes.threads.get_attachment(inbox_id, thread_id, attachment_id)
10- inboxes.threads.delete(inbox_id, thread_id)
11- threads.list(limit?, page_token?, labels?) — org-wide, all inboxes
12- threads.get(thread_id) — org-wide
13- threads.get_attachment(thread_id, attachment_id)
14
15Errors: SDK raises on 4xx/5xx. Rate limit: 429 with Retry-After.
16"""
17import os
18from dotenv import load_dotenv
19from agentmail import AgentMail
20
21load_dotenv()
22client = AgentMail(api_key=os.getenv("AGENTMAIL_API_KEY"))
23
24inbox_id = "agent@agentmail.to"
25
26# Per-inbox threads
27inbox_threads = client.inboxes.threads.list(inbox_id=inbox_id, limit=20)
28if inbox_threads.threads:
29    thread = client.inboxes.threads.get(inbox_id, inbox_threads.threads[0].thread_id)
30
31# Org-wide threads
32all_threads = client.threads.list(limit=50)
33if all_threads.threads:
34    single = client.threads.get(all_threads.threads[0].thread_id)
35    print(f"Thread has {len(single.messages)} messages")