For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
contact@agentmail.ccDiscord
DocumentationAPI ReferenceKnowledge BaseChangelog
DocumentationAPI ReferenceKnowledge BaseChangelog
  • API Reference
      • GETList Threads
      • GETSearch Threads
      • GETGet Thread
      • GETGet Attachment
      • PATCHUpdate Thread
      • DELDelete Thread
LogoLogo
contact@agentmail.ccDiscord
API ReferenceThreads

Search Threads

GET
/v0/threads/search
GET
/v0/threads/search
1from agentmail import AgentMail
2
3client = AgentMail(
4    api_key="YOUR_TOKEN_HERE",
5)
6
7client.threads.search(
8    q="q",
9)
1{
2  "count": 1,
3  "threads": [
4    {
5      "created_at": "2024-01-15T09:30:00Z",
6      "inbox_id": "inbox_id",
7      "labels": [
8        "labels",
9        "labels"
10      ],
11      "last_message_id": "last_message_id",
12      "message_count": 1,
13      "recipients": [
14        "recipients",
15        "recipients"
16      ],
17      "senders": [
18        "senders",
19        "senders"
20      ],
21      "size": 1,
22      "thread_id": "thread_id",
23      "timestamp": "2024-01-15T09:30:00Z",
24      "updated_at": "2024-01-15T09:30:00Z",
25      "attachments": [
26        {
27          "attachment_id": "attachment_id",
28          "size": 1,
29          "filename": "filename",
30          "content_type": "content_type",
31          "content_disposition": "inline",
32          "content_id": "content_id"
33        },
34        {
35          "attachment_id": "attachment_id",
36          "size": 1,
37          "filename": "filename",
38          "content_type": "content_type",
39          "content_disposition": "inline",
40          "content_id": "content_id"
41        }
42      ],
43      "highlights": {
44        "from": [
45          "from",
46          "from"
47        ],
48        "recipients": [
49          "recipients",
50          "recipients"
51        ],
52        "subject": [
53          "subject",
54          "subject"
55        ],
56        "text": [
57          "text",
58          "text"
59        ]
60      },
61      "preview": "preview",
62      "received_timestamp": "2024-01-15T09:30:00Z",
63      "sent_timestamp": "2024-01-15T09:30:00Z",
64      "subject": "subject"
65    },
66    {
67      "created_at": "2024-01-15T09:30:00Z",
68      "inbox_id": "inbox_id",
69      "labels": [
70        "labels",
71        "labels"
72      ],
73      "last_message_id": "last_message_id",
74      "message_count": 1,
75      "recipients": [
76        "recipients",
77        "recipients"
78      ],
79      "senders": [
80        "senders",
81        "senders"
82      ],
83      "size": 1,
84      "thread_id": "thread_id",
85      "timestamp": "2024-01-15T09:30:00Z",
86      "updated_at": "2024-01-15T09:30:00Z",
87      "attachments": [
88        {
89          "attachment_id": "attachment_id",
90          "size": 1,
91          "filename": "filename",
92          "content_type": "content_type",
93          "content_disposition": "inline",
94          "content_id": "content_id"
95        },
96        {
97          "attachment_id": "attachment_id",
98          "size": 1,
99          "filename": "filename",
100          "content_type": "content_type",
101          "content_disposition": "inline",
102          "content_id": "content_id"
103        }
104      ],
105      "highlights": {
106        "from": [
107          "from",
108          "from"
109        ],
110        "recipients": [
111          "recipients",
112          "recipients"
113        ],
114        "subject": [
115          "subject",
116          "subject"
117        ],
118        "text": [
119          "text",
120          "text"
121        ]
122      },
123      "preview": "preview",
124      "received_timestamp": "2024-01-15T09:30:00Z",
125      "sent_timestamp": "2024-01-15T09:30:00Z",
126      "subject": "subject"
127    }
128  ],
129  "limit": 1,
130  "next_page_token": "next_page_token"
131}

Full-text search across threads in the organization, ranked by relevance. The query is matched against senders, recipients, and subject (substring) and the message body (tokenized full text). Spam, trash, blocked, and unauthenticated threads are always excluded. limit cannot exceed 100.

Was this page helpful?
Previous

Get Thread

Next
Built with

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Query parameters

qstringRequired

Full-text search query. Matched against the sender, recipients, and subject (substring) and the message body (tokenized full text).

limitintegerOptional
Limit of number of items returned.
page_tokenstringOptional
Page token for pagination.
beforedatetimeOptional
Timestamp before which to filter by.
afterdatetimeOptional
Timestamp after which to filter by.

Response

This endpoint returns an object.
countinteger
Number of items returned.
threadslist of objects
Ordered by relevance, best match first.
limitinteger
Limit of number of items returned.
next_page_tokenstring
Page token for pagination.

Errors

400
Validation Error
404
Not Found Error