> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://agentinbox.space/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://agentinbox.space/_mcp/server.

# Метки

> Узнайте, как использовать метки для состояния, кампаний и фильтрации в агентных сценариях.

## Что такое `Labels`?

`Labels` — простые строковые теги для `Messages` и `Threads`. Это основной способ упорядочивать переписки и вести состояние: автоматически раскладывать треды по кампаниям, сегментировать лиды в аутриче или классифицировать входящие по уровню запроса.

У `Message` может быть несколько `Labels` — гибкая модель для сложных процессов.

## Сценарии для `Labels`

#### Управление состоянием

Отслеживайте состояние диалога: агент ставит `needs-human-review`, если не уверен; супервайзер — `approved-to-send` на `Draft`.

#### Кампании

В аутриче помечайте каждое `Message` уникальной меткой кампании вроде `q4-2024-outreach` или `mercor-campaign` и второй меткой вроде `warm-lead`. Потом легко фильтровать и анализировать результаты.

#### Автоматическая сортировка

Входящий агент может ставить `billing-question`, `feature-request`, `bug-report` — дальше подключаются специализированные агенты или люди.

#### Прочитано / непрочитано

Отмечайте обработанные `Messages`: после обработки добавьте `read`, снимите `unread`. Фильтр `labels=["unread"]` даёт только новые письма — агент не крутит одно и то же. Примеры — в [Пометка сообщений как прочитанных](/messages#marking-messages-as-read).

## Основные операции

### 1. Метки при отправке `Message`

Массив `Labels` можно передать сразу при отправке.

**`Python`**

```python title="Python"
sent_message = client.inboxes.messages.send(
    inbox_id="outbound@agentinbox.space",
    to=["test@example.com"],
    subject="Following up on our conversation",
    text="Here is the information you requested.",
    labels=["follow-up", "q4-campaign"]
)
```

**`TypeScript`**

```typescript title="TypeScript"
const sentMessage = await client.inboxes.messages.send(
  "outbound@agentinbox.space",
  {
    to: ["test@example.com"],
    subject: "Following up on our conversation",
    text: "Here is the information you requested.",
    labels: ["follow-up", "q4-campaign"],
  }
);
```

**`CLI`**

```bash title="CLI"
# отправка с метками
agentinbox inboxes:messages send \
  --inbox-id outbound@agentinbox.space \
  --to test@example.com \
  --subject "Following up on our conversation" \
  --text "Here is the information you requested." \
  --label follow-up \
  --label q4-campaign
```

### 2. Добавить или снять метки у существующего `Message`

Метод `update` (PATCH): удобно менять состояние по ходу работы агента.

```python
# Добавим метку 'resolved'

client.messages.update(
inbox_id='outbound@domain.com',
message_id='<abc123@agentinbox.space>',
add_labels=["resolved"],
remove_labels=['unresolved']
)

```

**`TypeScript`**

```typescript title="TypeScript"
// Добавим метку 'resolved'


await client.inboxes.messages.update(
  "my_inbox@domain.com",
  "<abc123@agentinbox.space>",
  {
    addLabels: [
        "resolved"
    ],
    removeLabels: [
        "unresolved"
    ]
  }
)

```

**`CLI`**

```bash title="CLI"
# добавить и снять метки
agentinbox inboxes:messages update \
  --inbox-id outbound@domain.com \
  --message-id "<abc123@agentinbox.space>" \
  --add-label resolved \
  --remove-label unresolved
```

### 3. Фильтрация по `Labels`

Можно получать `Threads`, `Messages` и `Drafts` с фильтром по одной или нескольким меткам.

```python
# Треды кампании, которым нужен follow-up
filtered_threads = client.inboxes.threads.list(
    inbox_id = 'outbound-agent@domain.com',
    labels=[
        "q4-campaign",
        "follow_up"
    ]
)

print(f"Found {filtered_threads.count} threads that need a follow-up.")

```

**`TypeScript`**

```typescript title="TypeScript"
// Треды кампании, которым нужен follow-up
const filteredThreads = await client.inboxes.threads.list(
  "leads@agentinbox.space",
  {
    labels: [
      "q4-campaign",
      "follow_up"
    ]
  }
)


console.log(`Found ${filteredThreads.count} threads that need a follow-up.`);
```

**`CLI`**

```bash title="CLI"
# список тредов по меткам
agentinbox inboxes:threads list \
  --inbox-id outbound-agent@domain.com \
  --label q4-campaign \
  --label follow_up
```

## Скопировать в Cursor / Claude

**`Python`**

```python title="Python"
"""
Agent Inbox Labels — copy into Cursor/Claude.

Labels are string tags on Messages and Threads for state, campaigns, triage.

- Send: messages.send(..., labels=["campaign", "follow-up"])
- Update: inboxes.messages.update(inbox_id, message_id, add_labels=[...], remove_labels=[...])
- Filter: messages.list(inbox_id, labels=[...]), threads.list(inbox_id, labels=[...]), drafts.list(inbox_id, labels=[...])

Use kebab-case or snake_case consistently.
"""
from agentinbox import Agentinbox

client = Agentinbox(api_key="YOUR_API_KEY")

# Send with labels
client.inboxes.messages.send("out@agentinbox.space", to="user@example.com", subject="Hi", text="Body", labels=["q4-campaign"])

# Update labels
client.inboxes.messages.update("out@agentinbox.space", "<abc123@agentinbox.space>", add_labels=["resolved"], remove_labels=["pending"])

# Filter by labels
threads = client.inboxes.threads.list("out@agentinbox.space", labels=["q4-campaign", "follow-up"])
```

**`TypeScript`**

```typescript title="TypeScript"
/**
 * Agent Inbox Labels — copy into Cursor/Claude.
 *
 * Labels are string tags on Messages and Threads for state, campaigns, triage.
 *
 * - Send: messages.send(inboxId, { ..., labels: ["campaign", "follow-up"] })
 * - Update: messages.update(inboxId, messageId, { addLabels: [...], removeLabels: [...] })
 * - Filter: messages.list(inboxId, { labels: [...] }), threads.list(inboxId, { labels: [...] }), drafts.list(inboxId, { labels: [...] })
 *
 * Use kebab-case or camelCase consistently.
 */
import { AgentinboxClient } from "agentinbox";

const client = new AgentinboxClient({ apiKey: "YOUR_API_KEY" });

async function main() {
  await client.inboxes.messages.send("out@agentinbox.space", {
    to: "user@example.com",
    subject: "Hi",
    text: "Body",
    labels: ["q4-campaign"],
  });
  await client.inboxes.messages.update("out@agentinbox.space", "<abc123@agentinbox.space>", {
    addLabels: ["resolved"],
    removeLabels: ["pending"],
  });
  const threads = await client.inboxes.threads.list("out@agentinbox.space", { labels: ["q4-campaign", "follow-up"] });
}
main();
```

## Рекомендации

* **Единообразие:** договоритесь о стиле имён меток (`kebab-case`, `snake_case` и т.д.).
* **Префиксы:** для состояний используйте префиксы вроде `status-pending` или `priority-high`.
* **Не перегружайте метками:** много меток на одно сообщение возможно, но лучше держать набор осмысленным и компактным.

> **Скоро: авторазметка на ИИ**
>
> Мы делаем авторазметку на ИИ: агент задаст набор `Labels` и инструкции, а Agent Inbox будет сам проставлять метки входящим `Messages` по содержанию.