收信

标签与分类

自动将发出和收到的邮件归入标签，并为智能体分配一个其会话永远不会离开的分类。

标签

标签的作用类似 Gmail 中的文件夹。一封邮件最多可以带 10 个标签，一个工作区最多可以有 200 个标签。使用 POST /labels 创建标签，使用 GET /labels 列出标签及其邮件数和未读数，使用 GET /emails?label=Billing 读取某个标签下的邮件。在任何地方都可以通过名称或 lbl_ ID 引用标签。

发送到标签

POST /emails 请求体
{
  "from": "Orders <orders@example.com>",
  "to": [
    "customer@example.net"
  ],
  "subject": "Order 1042",
  "text": "Reply with a delivery window.",
  "labels": [
    "Agent/Orders"
  ]
}

不存在的标签名称会被自动创建。该会话中之后的每一封邮件（包括客户的回复）都会继承该会话的标签。

分类（bucket）

创建标签时设置 "skip_inbox": true，即可将其变为分类。收到的邮件如果获得了分类标签（无论是通过归档规则、作为已加标签会话的回复，还是通过 POST /emails/:id/labels），都会被归档，因此只会出现在该标签中，永远不会出现在收件箱里。已发送的邮件从不出现在收件箱中。这样一来，智能体的任务会话无论收发，都集中在同一个地方。

POST /labels 请求体
{
  "name": "Agent/Orders",
  "skip_inbox": true,
  "rules": [
    {
      "inbox_id": "inb_…"
    }
  ],
  "apply_to_existing": true
}

归档规则

规则会自动归档新邮件。规则上设置的每个条件都必须匹配：inbox_id（收件地址）、direction（in 或 out），以及对 from、to（To 和 Cc）和 subject 的不区分大小写的子串匹配。规则自身的 skip_inbox 只会归档它匹配到的收到的邮件。使用 POST /labels/:id/rules 添加规则；apply_to_existing 还会归档已保留的邮件。

处理分类中的邮件

轮询 GET /emails?label=Agent%2FOrders&direction=in&unread=true，使用 GET /threads/:id 读取会话，使用 reply_to_email_id 回复，然后通过 PATCH /emails/:id {"read": true} 标记为已处理。使用 POST /emails/:id/labels {"add": [...], "remove": [...]} 将邮件移入或移出。MCP 服务器以 create_label、create_label_rule、label_email 和 list_emails 提供相同的操作。