import { createClient } from "@mailsai/sdk";
const client = createClient(); // reads MAILS_API_KEY
const result = await client.threads.list({ limit: 10 });
console.log(result);from mailsai import create_client
client = create_client() # reads MAILS_API_KEY
result = client.list_threads(limit=10)
print(result)curl 'https://api.mails.ai/v1/threads?limit=10' \
-H "Authorization: Bearer $MAILS_API_KEY"mails threads list --agent-id hello
mails threads list --status open --json{
"name": "mails_list_threads",
"arguments": { "limit": 10 }
}{
"data": [
{
"id": "thrd_01JZX8K3M9Q4P7VN2YB6RTDC0E",
"agent_id": "agt_01JZX8K3M9Q4P7VN2YB6RTDC0E",
"subject": "<subject>",
"root_message_id": "msg_01JZX8K3M9Q4P7VN2YB6RTDC0E",
"last_message_id": "msg_01JZX8K3M9Q4P7VN2YB6RTDC0E",
"last_message_at": "2026-10-04T12:00:00.000Z",
"message_count": 0,
"participants": ["jordan@example.com"],
"labels": ["<labels>"],
"label_ids": ["lbl_01JZX8K3M9Q4P7VN2YB6RTDC0E"],
"status": "open",
"read": false,
"folder": "inbox",
"trashed_at": "2026-10-04T12:00:00.000Z",
"assignee": {
"id": null,
"email": null,
"name": null
},
"assigned_at": "2026-10-04T12:00:00.000Z",
"notes_count": 0,
"test_mode": false,
"created_at": "2026-10-04T12:00:00.000Z",
"updated_at": "2026-10-04T12:00:00.000Z"
}
],
"has_more": false,
"next_cursor": "<next_cursor>"
}200 A page of threads (most-recent activity first).
400 Invalid request — malformed JSON or a field failed
validation. Also feature_not_enabled when this
server has a feature switched off (custom domains
before they are available).
401 Missing or invalid API key.
403 The API key lacks the required scope
(insufficient_scope), or the token belongs to an
app connected by sign-in and this operation is
closed to connected apps
(connected_app_not_allowed).
409 Conflict — duplicate resource, an in-progress
idempotent request, a draft or scheduled message
that started sending while it was being changed, or
a thread deleted for good while one of its messages
is being sent (duplicate_resource); or an agent
name more than one agent has (agent_name_conflict:
use the agent's id); or a status change on an
archived agent, since archiving cannot be undone
(agent_archived).
422 Unprocessable — agent paused, recipient suppressed,
a recipient at test.mails.ai other than
reply@test.mails.ai (unknown_test_address), or
abuse guard.
500 Internal server error.List threads
import { createClient } from "@mailsai/sdk";
const client = createClient(); // reads MAILS_API_KEY
const result = await client.threads.list({ limit: 10 });
console.log(result);from mailsai import create_client
client = create_client() # reads MAILS_API_KEY
result = client.list_threads(limit=10)
print(result)curl 'https://api.mails.ai/v1/threads?limit=10' \
-H "Authorization: Bearer $MAILS_API_KEY"mails threads list --agent-id hello
mails threads list --status open --json{
"name": "mails_list_threads",
"arguments": { "limit": 10 }
}{
"data": [
{
"id": "thrd_01JZX8K3M9Q4P7VN2YB6RTDC0E",
"agent_id": "agt_01JZX8K3M9Q4P7VN2YB6RTDC0E",
"subject": "<subject>",
"root_message_id": "msg_01JZX8K3M9Q4P7VN2YB6RTDC0E",
"last_message_id": "msg_01JZX8K3M9Q4P7VN2YB6RTDC0E",
"last_message_at": "2026-10-04T12:00:00.000Z",
"message_count": 0,
"participants": ["jordan@example.com"],
"labels": ["<labels>"],
"label_ids": ["lbl_01JZX8K3M9Q4P7VN2YB6RTDC0E"],
"status": "open",
"read": false,
"folder": "inbox",
"trashed_at": "2026-10-04T12:00:00.000Z",
"assignee": {
"id": null,
"email": null,
"name": null
},
"assigned_at": "2026-10-04T12:00:00.000Z",
"notes_count": 0,
"test_mode": false,
"created_at": "2026-10-04T12:00:00.000Z",
"updated_at": "2026-10-04T12:00:00.000Z"
}
],
"has_more": false,
"next_cursor": "<next_cursor>"
}200 A page of threads (most-recent activity first).
400 Invalid request — malformed JSON or a field failed
validation. Also feature_not_enabled when this
server has a feature switched off (custom domains
before they are available).
401 Missing or invalid API key.
403 The API key lacks the required scope
(insufficient_scope), or the token belongs to an
app connected by sign-in and this operation is
closed to connected apps
(connected_app_not_allowed).
409 Conflict — duplicate resource, an in-progress
idempotent request, a draft or scheduled message
that started sending while it was being changed, or
a thread deleted for good while one of its messages
is being sent (duplicate_resource); or an agent
name more than one agent has (agent_name_conflict:
use the agent's id); or a status change on an
archived agent, since archiving cannot be undone
(agent_archived).
422 Unprocessable — agent paused, recipient suppressed,
a recipient at test.mails.ai other than
reply@test.mails.ai (unknown_test_address), or
abuse guard.
500 Internal server error.Query Parameters
Page size (1–100).
Opaque cursor from a previous page's next_cursor.
Filter by agent id or name. A key tied to one agent always reads that agent's mail, and naming another agent is a 403.
Filter by thread status (open|closed|archived).
Which folder's threads to return, or all for every folder. Without it: every folder except trash.
false for unread threads only, true for read ones.
Only threads carrying this label (a name, or a label id lbl_…).
Only threads assigned to this member (an email, in any case, or a user id usr_…; one who is not a member matches no thread), none for threads assigned to nobody, or any for threads assigned to someone. me is the person signed in, in the dashboard or through an app connected by sign-in; a plain API key has no person behind it, so me from one is a 422.
live for threads that hold live mail, test for threads of test mail only (test_mode: true), all for both. Without it, a key lists the threads of its own mode, as the unread counts of GET /v1/agents/{id}/inbox count them: a live key does not see the test mail POST /v1/test/inbound delivers.
Case-insensitive substring of the subject or participant addresses. For word search across all mail, use GET /v1/search.
Response
The items on this page, at most limit of them.
True when more items follow this page: pass next_cursor as cursor to get them.
Pass as cursor to fetch the next page. Absent on the last page.
Was this page helpful?