Skip to navigation
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.

# You'll need an inbox ID to list threads from.
inbox_id = "inbound-agent@agentmail.to"
# This loads all threads within the specified Inbox
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.
# By not providing an inbox_id, we get all threads in the organization
all_threads = client.threads.list()
print(f"Found {all_threads.count} threads across the entire organization.")

Searching Threads

Full-text search finds Threads by keyword across the sender, recipients, subject, and message body, ranked by relevance. Like listing, it works per-Inbox or across the whole Organization — omit the inbox_id to search every Inbox. Spam, trash, blocked, and unauthenticated threads are excluded, and limit cannot exceed 100.

# search every inbox in the organization
results = client.threads.search(q="invoice overdue")
for thread in results.threads:
    print(thread.thread_id, thread.subject)
    # highlights shows which fields matched, with matched terms wrapped in **
    if thread.highlights:
        print(thread.highlights)
# or scope the search to a single inbox
inbox_results = client.inboxes.threads.search(
    inbox_id="inbound-agent@agentmail.to",
    q="invoice overdue",
)

Need an exact-field filter instead of relevance ranking? threads.list accepts senders, recipients, and subject substring filters and keeps the usual newest-first ordering.

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.

thread_id = "thread_456def"
# This loads a single thread and its messages
thread = client.threads.get(
thread_id="thread_id"
)
print(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.

"""
AgentMail Threads — copy into Cursor/Claude.
Setup: pip install agentmail python-dotenv. Set AGENTMAIL_API_KEY in .env.
API reference:
- inboxes.threads.list(inbox_id, limit?, page_token?, labels?, before?, after?, ascending?, senders?, recipients?, subject?)
- inboxes.threads.search(inbox_id, q, limit?, page_token?, before?, after?) — full-text, relevance-ranked
- inboxes.threads.get(inbox_id, thread_id)
- inboxes.threads.get_attachment(inbox_id, thread_id, attachment_id)
- inboxes.threads.delete(inbox_id, thread_id)
- threads.list(limit?, page_token?, labels?, senders?, recipients?, subject?) — org-wide, all inboxes
- threads.search(q, limit?, page_token?, before?, after?) — org-wide full-text
- threads.get(thread_id) — org-wide
- threads.get_attachment(thread_id, attachment_id)
Errors: SDK raises on 4xx/5xx. Rate limit: 429 with Retry-After.
"""
import os
from dotenv import load_dotenv
from agentmail import AgentMail
load_dotenv()
client = AgentMail(api_key=os.getenv("AGENTMAIL_API_KEY"))
inbox_id = "agent@agentmail.to"
# Per-inbox threads
inbox_threads = client.inboxes.threads.list(inbox_id=inbox_id, limit=20)
if inbox_threads.threads:
    thread = client.inboxes.threads.get(inbox_id, inbox_threads.threads[0].thread_id)
# Org-wide threads
all_threads = client.threads.list(limit=50)
if all_threads.threads:
    single = client.threads.get(all_threads.threads[0].thread_id)
    print(f"Thread has {len(single.messages)} messages")