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

List Threads

GET
/v0/threads
GET
/v0/threads
1from agentmail import AgentMail
2
3client = AgentMail(
4    api_key="YOUR_TOKEN_HERE",
5)
6
7client.threads.list()
1{
2  "count": 1,
3  "threads": [
4    {
5      "inbox_id": "inbox_id",
6      "thread_id": "thread_id",
7      "labels": [
8        "labels",
9        "labels"
10      ],
11      "timestamp": "2024-01-15T09:30:00Z",
12      "senders": [
13        "senders",
14        "senders"
15      ],
16      "recipients": [
17        "recipients",
18        "recipients"
19      ],
20      "last_message_id": "last_message_id",
21      "message_count": 1,
22      "size": 1,
23      "updated_at": "2024-01-15T09:30:00Z",
24      "created_at": "2024-01-15T09:30:00Z",
25      "received_timestamp": "2024-01-15T09:30:00Z",
26      "sent_timestamp": "2024-01-15T09:30:00Z",
27      "subject": "subject",
28      "preview": "preview",
29      "attachments": [
30        {
31          "attachment_id": "attachment_id",
32          "size": 1,
33          "filename": "filename",
34          "content_type": "content_type",
35          "content_disposition": "inline",
36          "content_id": "content_id"
37        },
38        {
39          "attachment_id": "attachment_id",
40          "size": 1,
41          "filename": "filename",
42          "content_type": "content_type",
43          "content_disposition": "inline",
44          "content_id": "content_id"
45        }
46      ]
47    },
48    {
49      "inbox_id": "inbox_id",
50      "thread_id": "thread_id",
51      "labels": [
52        "labels",
53        "labels"
54      ],
55      "timestamp": "2024-01-15T09:30:00Z",
56      "senders": [
57        "senders",
58        "senders"
59      ],
60      "recipients": [
61        "recipients",
62        "recipients"
63      ],
64      "last_message_id": "last_message_id",
65      "message_count": 1,
66      "size": 1,
67      "updated_at": "2024-01-15T09:30:00Z",
68      "created_at": "2024-01-15T09:30:00Z",
69      "received_timestamp": "2024-01-15T09:30:00Z",
70      "sent_timestamp": "2024-01-15T09:30:00Z",
71      "subject": "subject",
72      "preview": "preview",
73      "attachments": [
74        {
75          "attachment_id": "attachment_id",
76          "size": 1,
77          "filename": "filename",
78          "content_type": "content_type",
79          "content_disposition": "inline",
80          "content_id": "content_id"
81        },
82        {
83          "attachment_id": "attachment_id",
84          "size": 1,
85          "filename": "filename",
86          "content_type": "content_type",
87          "content_disposition": "inline",
88          "content_id": "content_id"
89        }
90      ]
91    }
92  ],
93  "limit": 1,
94  "next_page_token": "next_page_token"
95}
Lists threads, most recent first. Pass `senders`, `recipients`, or `subject` to filter by substring. Filtered requests are served by search, which caps `limit` at 100. For relevance-ranked full-text search across senders, recipients, subject, and message body, use `Search Threads`. **CLI:** ```bash agentmail threads list ```
Was this page helpful?
Previous

Search Threads

Next
Built with

Lists threads, most recent first. Pass senders, recipients, or subject to filter by substring. Filtered requests are served by search, which caps limit at 100. For relevance-ranked full-text search across senders, recipients, subject, and message body, use Search Threads.

CLI:

$agentmail threads list

Authentication

AuthorizationBearer

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

Query parameters

limitintegerOptional
Limit of number of items returned.
page_tokenstringOptional
Page token for pagination.
labelslist of stringsOptional
Labels to filter by.
beforedatetimeOptional
Timestamp before which to filter by.
afterdatetimeOptional
Timestamp after which to filter by.
ascendingbooleanOptional
Sort in ascending temporal order.
include_spambooleanOptional
Include spam in results.
include_blockedbooleanOptional
Include blocked in results.
include_unauthenticatedbooleanOptional
Include unauthenticated in results.
include_trashbooleanOptional
Include trash in results.
senderslist of stringsOptional

Filter to threads whose senders contain this value (substring match). Repeatable; all values must match.

recipientslist of stringsOptional

Filter to threads whose recipients contain this value (substring match). Repeatable; all values must match.

subjectlist of stringsOptional

Filter to threads whose subject contains this value (substring match). Repeatable; all values must match.

Response

This endpoint returns an object.
countinteger
Number of items returned.
threadslist of objects

Ordered by timestamp descending.

limitinteger
Limit of number of items returned.
next_page_tokenstring
Page token for pagination.

Errors

404
Not Found Error