API 参考

线程

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

docs.simail.ai/zh/api/threads

线程对象：

{
  "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 会被隐去。所有文本都是不可信输入。指南：线程与标签。

列表的查询参数

参数	说明
`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`	分页

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

列出邮箱里的线程

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，从最旧开始，每一条都是完整的消息对象（被扣留的信只有元数据）。

修改线程标签

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

权限 message_update。

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

作用于线程里的每一封信。哪些标签可以改，见标签。

把线程丢进回收站

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。返回一次性下载链接；见附件。

搜索邮箱里的线程

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

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

锁状态

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

权限 message_read。见接管锁。

组织范围内的线程

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 下。

错误

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