# 标签

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

> 消息和线程上的系统标签与自定义标签、如何按标签过滤，以及 agent 可以改哪些。

标签是消息上的短字符串。一个线程的标签是它各条消息标签的并集。

## 系统标签

| 标签 | 设置者 | agent 可否修改 |
|---|---|---|
| `received` | simail，在来信上 | 不可以 |
| `sent` | simail，在外发邮件上 | 不可以 |
| `unread` | simail，在来信上 | 可以 |
| `important` | 你 | 可以 |
| `draft` | simail | 不可以 |
| `held` | simail；人放行该消息后清除 | 不可以 |
| `spam` | simail | 不可以 |
| `blocked` | simail（发件人在拦截名单上） | 不可以 |
| `trash` | 对消息或线程执行 `DELETE` | 不可以（只能通过删除） |

## 自定义标签

其他不超过 64 个字符的小写字符串（`a-z`、`0-9`、`-`、`_`、`.`、`/`）都是自定义标签，例如 `orders` 或 `needs-human`。agent 可以自由添加和移除自定义标签。

## 修改标签

`PATCH /v0/inboxes/{inbox_id}/messages/{message_id}`

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

`POST /v0/inboxes/{inbox_id}/messages/batch-update`

都需要 `message_update`，正文为：

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

试图修改 agent 不能改的标签会返回 `400 validation_error`。变更会发布 `label.added` 和 `label.removed`。发信时可以用 `labels` 给发出的那一份设置标签。

## 过滤

列表和搜索接口接受 `labels=a,b`（必须全部匹配）。`spam`、`blocked` 和 `trash` 默认不出现在列表里，除非你传入 `include_spam`、`include_blocked` 或 `include_trash`，每一个都需要对应的 `label_*_read` 权限。

MCP：`list_labels` 和 `update_labels`。