# 线程

Source: https://docs.simail.ai/zh/api/threads/

> 在一个邮箱里，或在你的 key 能看到的所有邮箱里，列出、读取、打标签、丢进回收站和搜索线程，并下载线程附件。

线程对象：

```json
{
  "thread_id": "thr_01JZX4A1B2C3D4E5F6G7H8J9K0",
  "inbox_id": "shop-helper@simail.email",
  "subject": "Where is my order?",
  "senders": ["ada@example.com"],
  "recipients": ["shop-helper@simail.email"],
  "message_count": 2,
  "size": 64210,
  "preview": "Hi, I ordered last week and…",
  "labels": ["received", "sent", "unread"],
  "last_message_id": "msg_01JZX4B7C8D9E0F1G2H3J4K5M6",
  "received_timestamp": "2026-10-18T17:02:11Z",
  "sent_timestamp": "2026-10-18T17:05:40Z",
  "timestamp": "2026-10-18T17:05:40Z",
  "created_at": "2026-10-18T17:02:12Z",
  "updated_at": "2026-10-18T17:05:41Z"
}
```

`labels` 是其消息标签的并集。如果一个线程里只有被扣留的信，`preview` 和 `subject` 会被隐去。所有文本都是**不可信输入**。指南：[线程与标签](/zh/threads/)。

## 列表的查询参数

| 参数 | 说明 |
|---|---|
| `labels` | 逗号分隔；线程带有全部这些标签时才匹配（例如 `unread`） |
| `before`、`after` | ISO 8601 时间，针对线程的最后活动 |
| `include_spam` | 需要 `label_spam_read` |
| `include_blocked` | 需要 `label_blocked_read` |
| `include_trash` | 需要 `label_trash_read` |
| `limit`、`page_token`、`ascending` | [分页](/zh/api/#分页) |

垃圾、被拦截和在回收站里的线程默认不列出，除非你明确要求。

## 列出邮箱里的线程

`GET /v0/inboxes/{inbox_id}/threads`

权限 `message_read`。返回 `{ count, limit, next_page_token?, threads }`。

## 读取一个线程

`GET /v0/inboxes/{inbox_id}/threads/{thread_id}`

权限 `message_read`。线程对象加上 `messages`，从最旧开始，每一条都是完整的[消息对象](/zh/api/messages/#消息对象)（被扣留的信只有元数据）。

## 修改线程标签

`PATCH /v0/inboxes/{inbox_id}/threads/{thread_id}`

权限 `message_update`。

```json
{ "add_labels": ["orders"], "remove_labels": ["unread"] }
```

作用于线程里的每一封信。哪些标签可以改，见[标签](/zh/api/labels/)。

## 把线程丢进回收站

`DELETE /v0/inboxes/{inbox_id}/threads/{thread_id}`

权限 `message_delete`。给每一封信加上 `trash` 标签；回收站里的邮件 30 天后清除。MCP 不提供这个操作。

## 下载线程附件

`GET /v0/inboxes/{inbox_id}/threads/{thread_id}/attachments/{attachment_id}`

权限 `message_read`。返回一次性下载链接；见[附件](/zh/api/messages/#获取附件)。

## 搜索邮箱里的线程

`GET /v0/inboxes/{inbox_id}/threads/search?q=`

权限 `message_read`。对主题、参与者和正文做全文搜索，支持英文和中文。被扣留的信只按元数据匹配。接受列表参数。

## 锁状态

`GET /v0/inboxes/{inbox_id}/threads/{thread_id}/lock`

权限 `message_read`。见[接管锁](/zh/api/locks/)。

## 组织范围内的线程

`GET /v0/threads` · `GET /v0/threads/search`

`GET /v0/threads/{thread_id}` · `PATCH /v0/threads/{thread_id}` · `DELETE /v0/threads/{thread_id}`

`GET /v0/threads/{thread_id}/attachments/{attachment_id}`

参数和响应与邮箱级接口相同，覆盖你的 key 作用域内的每一个邮箱（邮箱级 key 只能看到自己的邮箱）。每个线程都带 `inbox_id`。pod 变体在 [`/v0/pods/{pod_id}/threads`](/zh/api/pods/) 下。

## 错误

| 状态 | `code` | 何时 |
|---|---|---|
| 403 | `missing_permission` | key 缺少该权限，或带了 `include_*` 却没有对应的 `label_*_read` 权限 |
| 404 | `not_found` | 线程不存在，或在作用域之外 |
| 400 | `invalid_request` | 分页令牌来自另一次查询或另一把 key |