AgentMail Changelog

Summary

You can now search messages and threads by keyword. Full-text search ranks results by relevance across the sender, recipients, subject, and message body, and works per-inbox or across your entire organization. List endpoints also gained substring filters, so you can narrow a list to a specific sender, recipient, or subject without paging through everything. Build agents that find the right conversation instead of scanning every thread.

What’s new?

New endpoints:

• GET /v0/inboxes/:inbox_id/messages/search - Full-text search of messages in an inbox, ranked by relevance.
• GET /v0/threads/search - Org-wide full-text search across threads in every inbox.
• GET /v0/inboxes/:inbox_id/threads/search - Full-text search of threads in a single inbox.
• GET /v0/pods/:pod_id/threads/search - Full-text search of threads in a pod.

New features:

• Full-text search: A q query matches against the sender, recipients, and subject (substring) and the message body (tokenized full text). Results are ordered by relevance. Spam, trash, blocked, and unauthenticated items are always excluded, and limit is capped at 100.
• Match highlights: Each search result includes an optional highlights object with the matched fragments per field, with matched terms wrapped in **. A field appears only when it matched, so the present keys also tell you which fields produced the hit.

Changes:

• GET /v0/inboxes/:inbox_id/messages now accepts from, to, and subject substring filters. to matches the to, cc, or bcc fields.
• GET /v0/threads, GET /v0/inboxes/:inbox_id/threads, and GET /v0/pods/:pod_id/threads now accept senders, recipients, and subject substring filters.
• Filtered list requests are served by search and cap limit at 100; results keep the usual newest-first ordering.

Use cases

Build agents that:

• Pull up every thread mentioning an order number, invoice, or customer name across all of your inboxes
• Find the conversation a reply belongs to by searching the subject or body, instead of paging through history
• Narrow a list to a single sender or recipient before processing, using the new substring filters
• Surface the matched snippet to a human reviewer using per-field highlights

1
from agentmail import AgentMail
2
3
client = AgentMail(api_key="your-api-key")
4
5
# org-wide full-text search across every inbox
6
results = client.threads.search(q="invoice overdue")
7
8
for thread in results.threads:
9
    print(thread.thread_id, thread.subject)
10
    # highlights tells you which fields matched
11
    if thread.highlights:
12
        print(thread.highlights)
13
14
# scope a search to one inbox's messages
15
inbox_results = client.inboxes.messages.search(
16
    inbox_id="support@agentmail.to",
17
    q="refund requested",
18
)
19
20
# or just filter a list by subject, no relevance ranking
21
filtered = client.inboxes.messages.list(
22
    inbox_id="support@agentmail.to",
23
    subject=["invoice"],
24
)