import { createClient } from "@mailsai/sdk";

const client = createClient(); // reads MAILS_API_KEY

const result = await client.threads.get(
  "thrd_01JZX8K3M9Q4P7VN2YB6RTDC0E",
);
console.log(result);

from mailsai import create_client

client = create_client()  # reads MAILS_API_KEY

result = client.get_thread(
    "thrd_01JZX8K3M9Q4P7VN2YB6RTDC0E",
)
print(result)

curl 'https://api.mails.ai/v1/threads/thrd_01JZX8K3M9Q4P7VN2YB6RTDC0E' \
  -H "Authorization: Bearer $MAILS_API_KEY"

mails threads get thrd_01JABC

{
  "name": "mails_get_thread",
  "arguments": {
    "thread_id": "thrd_01JZX8K3M9Q4P7VN2YB6RTDC0E"
  }
}

{
  "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",
  "test_mode": false,
  "created_at": "2026-10-04T12:00:00.000Z",
  "updated_at": "2026-10-04T12:00:00.000Z",
  "messages": [
    {
      "id": "msg_01JZX8K3M9Q4P7VN2YB6RTDC0E",
      "direction": "outbound",
      "to": [null],
      "subject": "<subject>",
      "body_text": "<body_text>",
      "snippet": "<snippet>",
      "status": "<status>",
      "sent_at": "2026-10-04T12:00:00.000Z",
      "scheduled_at": "2026-10-04T12:00:00.000Z",
      "created_at": "2026-10-04T12:00:00.000Z"
    }
  ]
}

200  The thread plus its inbound + outbound messages.
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).
500  Internal server error.

Retrieve a thread with messages

GET/v1/threads/{id}scope · read

import { createClient } from "@mailsai/sdk";

const client = createClient(); // reads MAILS_API_KEY

const result = await client.threads.get(
  "thrd_01JZX8K3M9Q4P7VN2YB6RTDC0E",
);
console.log(result);

from mailsai import create_client

client = create_client()  # reads MAILS_API_KEY

result = client.get_thread(
    "thrd_01JZX8K3M9Q4P7VN2YB6RTDC0E",
)
print(result)

curl 'https://api.mails.ai/v1/threads/thrd_01JZX8K3M9Q4P7VN2YB6RTDC0E' \
  -H "Authorization: Bearer $MAILS_API_KEY"

mails threads get thrd_01JABC

{
  "name": "mails_get_thread",
  "arguments": {
    "thread_id": "thrd_01JZX8K3M9Q4P7VN2YB6RTDC0E"
  }
}

{
  "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",
  "test_mode": false,
  "created_at": "2026-10-04T12:00:00.000Z",
  "updated_at": "2026-10-04T12:00:00.000Z",
  "messages": [
    {
      "id": "msg_01JZX8K3M9Q4P7VN2YB6RTDC0E",
      "direction": "outbound",
      "to": [null],
      "subject": "<subject>",
      "body_text": "<body_text>",
      "snippet": "<snippet>",
      "status": "<status>",
      "sent_at": "2026-10-04T12:00:00.000Z",
      "scheduled_at": "2026-10-04T12:00:00.000Z",
      "created_at": "2026-10-04T12:00:00.000Z"
    }
  ]
}

200  The thread plus its inbound + outbound messages.
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).
500  Internal server error.

Path Parameters

idstringrequired

Thread id (thrd_…).

Response

idstring

Thread id (thrd_…).

agent_idstring

Id (agt_…) of the agent the thread belongs to; a thread holds one agent's mail only.

subjectstring

The subject of the thread's first message, without one leading Re:, Fwd: or Fw:. Empty when that message had no subject.

root_message_idstring

Id of the message that started the thread: msg_… for one the agent sent, rcv_… for one it received.

last_message_idstring

Id of the message that joined the thread most recently (msg_… or rcv_…).

last_message_atstring

When the latest message joined the thread. The thread list is ordered by it, newest first.

message_countinteger

How many messages have joined the thread, sent and received.

participantsstring[]

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.

labelsstring[]

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.

label_idsstring[]

Ids (lbl_…) of the label objects whose names are on this thread.

statusstring

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).

One of: open, closed, archived

readboolean

False once new mail arrives; set it with PATCH.

folderstring

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.

One of: inbox, archive, spam, trash, sent

trashed_atstring

When the thread was moved to trash. Present only while it is there.

test_modeboolean

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.

created_atstring

When the thread was created, with its first message.

updated_atstring

When the thread last changed: a message joined it, or its read state, folder, status or labels changed.

messagesobject[]

Every message in the thread, oldest first: sent ones by sent_at (created_at until sent), received ones by received_at. All come at once, with no paging; direction tells the two kinds apart.

Was this page helpful?