import { createClient } from "@mailsai/sdk";
const client = createClient(); // reads MAILS_API_KEY
const result = await client.threads.update(
"thrd_01JZX8K3M9Q4P7VN2YB6RTDC0E",
{
status: "closed",
labels: ["resolved", "shipping"],
},
);
console.log(result);from mailsai import create_client
client = create_client() # reads MAILS_API_KEY
result = client.update_thread(
"thrd_01JZX8K3M9Q4P7VN2YB6RTDC0E",
status="closed",
labels=["resolved", "shipping"],
)
print(result)curl -X PATCH 'https://api.mails.ai/v1/threads/thrd_01JZX8K3M9Q4P7VN2YB6RTDC0E' \
-H "Authorization: Bearer $MAILS_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"status": "closed",
"labels": ["resolved", "shipping"]
}'mails threads update thrd_01JABC --status closed \
--labels resolved,shipping
mails threads update thrd_01JABC --add-labels billing \
--remove-labels waiting{
"name": "mails_threads_update",
"arguments": {
"thread_id": "thrd_01JZX8K3M9Q4P7VN2YB6RTDC0E",
"labels": ["resolved", "shipping"],
"status": "closed"
}
}{
"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": "usr_01JZX8K3M9Q4P7VN2YB6RTDC0E",
"email": "jordan@example.com",
"name": "<name>"
},
"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",
"previous": {
"folder": "<folder>",
"status": "<status>",
"read": false,
"labels": ["<labels>"],
"assignee": {
"id": "usr_01JZX8K3M9Q4P7VN2YB6RTDC0E",
"email": "jordan@example.com",
"name": "<name>"
}
}
}200 The updated thread (no messages array), with what
the request changed in previous.
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).
404 Resource not found in this workspace, or the agent
a send names is archived (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.Update a thread
read, folder, status, labels, label_ids, add_labels, remove_labels and assignee; emits thread.updated when its read state, folder, status or labels changed.import { createClient } from "@mailsai/sdk";
const client = createClient(); // reads MAILS_API_KEY
const result = await client.threads.update(
"thrd_01JZX8K3M9Q4P7VN2YB6RTDC0E",
{
status: "closed",
labels: ["resolved", "shipping"],
},
);
console.log(result);from mailsai import create_client
client = create_client() # reads MAILS_API_KEY
result = client.update_thread(
"thrd_01JZX8K3M9Q4P7VN2YB6RTDC0E",
status="closed",
labels=["resolved", "shipping"],
)
print(result)curl -X PATCH 'https://api.mails.ai/v1/threads/thrd_01JZX8K3M9Q4P7VN2YB6RTDC0E' \
-H "Authorization: Bearer $MAILS_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"status": "closed",
"labels": ["resolved", "shipping"]
}'mails threads update thrd_01JABC --status closed \
--labels resolved,shipping
mails threads update thrd_01JABC --add-labels billing \
--remove-labels waiting{
"name": "mails_threads_update",
"arguments": {
"thread_id": "thrd_01JZX8K3M9Q4P7VN2YB6RTDC0E",
"labels": ["resolved", "shipping"],
"status": "closed"
}
}{
"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": "usr_01JZX8K3M9Q4P7VN2YB6RTDC0E",
"email": "jordan@example.com",
"name": "<name>"
},
"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",
"previous": {
"folder": "<folder>",
"status": "<status>",
"read": false,
"labels": ["<labels>"],
"assignee": {
"id": "usr_01JZX8K3M9Q4P7VN2YB6RTDC0E",
"email": "jordan@example.com",
"name": "<name>"
}
}
}200 The updated thread (no messages array), with what
the request changed in previous.
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).
404 Resource not found in this workspace, or the agent
a send names is archived (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.Path Parameters
Thread id.
Body Parameters
Label names, up to 50, each at most 64 characters. Replaces the thread's labels. Any such name works; a name that matches a label object picks up its id and colour.
Label object ids (lbl_…). Replaces the thread's labels with those labels' names. Sent together with labels, the thread gets both.
"archived" also files the thread in archive; "open" or "closed" on an archived thread moves it back to the inbox.
Mark the thread read (true) or unread (false).
Move the thread to inbox, archive, spam, trash or sent. archive also sets status "archived", and moving an archived thread anywhere else reopens it. sent works only while every message in the thread is one you sent (422 otherwise). A thread in trash is deleted for good 30 days after it was moved there.
Assign the thread to a member of the workspace, by email address (any case) or user id (usr_…); null unassigns it. 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. Someone who is not a member is refused with 422 assignee_not_member; GET /v1/members lists who can be assigned. Raises thread.assigned or thread.unassigned when the assignee changes.
Label names to put on the thread, keeping the ones it has (ignoring case, a name it already carries changes nothing). Applied after labels and label_ids when sent with them. A thread holds up to 50 labels (422 past that).
Label names to take off the thread, ignoring case; a name it does not carry changes nothing. Applied after labels and label_ids when sent with them. A name may not be in both add_labels and remove_labels (422).
add_labels and remove_labels add and take off label names without replacing the rest, after labels or label_ids when those are sent too; a name in both is a 422. assignee gives the thread to a member of the workspace (an email, in any case, or a user id usr_…, as GET /v1/members lists them) or, as null, to nobody, and emits thread.assigned or thread.unassigned; assigning the member it already has changes nothing and emits nothing. Anyone else is a 422 assignee_not_member, a member of another workspace too. folder: "archive" and status: "archived" move together, and moving an archived thread anywhere else reopens it. folder: "sent" works only while every message in the thread is one the agent sent; a thread holding a received message is a 422. So is status: "archived" with any folder but archive. A test key cannot move a thread holding live mail to trash or assign it (403 live_mode_required).
Response
Thread id (thrd_…).
Id (agt_…) of the agent the thread belongs to; a thread holds one agent's mail only.
The subject of the thread's first message, without one leading Re:, Fwd: or Fw:. Empty when that message had no subject.
Id of the message that started the thread: msg_… for one the agent sent, rcv_… for one it received.
Id of the message that joined the thread most recently (msg_… or rcv_…).
When the latest message joined the thread. The thread list is ordered by it, newest first.
How many messages have joined the thread, sent and received.
Every address the thread has involved, in lower case and without repeats: the agent's own, the senders of received mail and the recipients of sent mail.
Label names, up to 50, each at most 64 characters. Any such name works; names that match a label object also appear in label_ids.
Ids (lbl_…) of the label objects whose names are on this thread.
open (every new thread), closed or archived, changed with PATCH. archived goes with folder archive, and only an open thread takes in new mail matched by its subject (mail from someone already in the thread).
False once new mail arrives; set it with PATCH.
inbox, archive, spam, trash or sent. archive goes with status archived. sent holds a thread whose messages are all ones the agent sent, until a reply moves it to the inbox. Threads in trash are deleted for good 30 days after they were trashed.
When the thread was moved to trash. Present only while it is there.
When the thread was assigned to its assignee, or null while it is assigned to nobody.
How many notes the team has left on the thread (GET /v1/threads/{id}/notes).
True when the thread holds no live mail: every message in it was sent with a test key (mk_test_…) or delivered through POST /v1/test/inbound. A thread with any live message is live. Its thread.* events carry the same test_mode, and GET /v1/threads lists a key's own mode unless mode says otherwise.
When the thread was created, with its first message.
When the thread last changed: a message joined it, or its read state, folder, status, labels or assignee changed.
The fields this request changed, as they stood just before it, and only those: empty when nothing changed. Sending them back in another PATCH undoes the request, which is safer than a value read earlier, since the thread may have moved since.
Was this page helpful?