Threads

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

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 {all_threads.count} threads across the entire organization.")

1
# search every inbox in the organization
2
results = client.threads.search(q="invoice overdue")
3
4
for thread in results.threads:
5
    print(thread.thread_id, thread.subject)
6
    # highlights shows which fields matched, with matched terms wrapped in **
7
    if thread.highlights:
8
        print(thread.highlights)
9
10
# or scope the search to a single inbox
11
inbox_results = client.inboxes.threads.search(
12
    inbox_id="inbound-agent@agentmail.to",
13
    q="invoice overdue",
14
)

1
thread_id = "thread_456def"
2
3
# This loads 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.thread_id} with {len(thread.messages)} messages.")

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