> 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.

# Списки

> Узнайте, как использовать списки, чтобы контролировать, кому агенты могут отправлять письма и от кого принимать.

## Что такое списки?

`Lists` фильтруют почту: разрешают или блокируют конкретные адреса или домены. Шесть типов по двум осям:

* **Направление**: `send`, `receive` или `reply`
* **Тип**: `allow` или `block`

| Список        | Описание                                           |
| ------------- | -------------------------------------------------- |
| Receive allow | Принимать письма только с этих адресов или доменов |
| Receive block | Отклонять письма с этих адресов или доменов        |
| Send allow    | Отправлять только на эти адреса или домены         |
| Send block    | Запретить отправку на эти адреса или домены        |
| Reply allow   | Принимать ответы только с этих адресов или доменов |
| Reply block   | Отклонять ответы с этих адресов или доменов        |

Запись — либо полный email (например `partner@example.com`), либо целый домен (например `example.com`).

## Область действия (scoping)

Списки задаются на трёх уровнях. Более узкая область перекрывает более широкую:

* **Organization**: на всю организацию — `client.lists`.
* **Pod**: на все inbox в pod — `client.pods.lists`.
* **Inbox**: на один ящик — `client.inboxes.lists`.

При решении «разрешить или заблокировать» сначала проверяется самый конкретный уровень. Если сработал список уровня inbox, pod и org не проверяются.

## Списки для ответов (reply)

Направление `reply` относится к входящим письмам, которые являются ответами на ранее отправленные вами. По заголовку `In-Reply-To` определяется, ответ это или нет:

* **Если это ответ** на исходящее сообщение — проверяются только reply-списки. Receive-списки не используются.
* **Если это не ответ** — проверяются только receive-списки. Reply-списки не используются.

Ветки независимы. По умолчанию при пустых reply-списках все ответы разрешены. Ограничить ответы можно через reply allow или reply block.

## Примеры SDK

### Записи списка

Получить записи с опциональной пагинацией.

**`Python`**

```python title="Python"
entries = client.lists.list("receive", "allow", limit=10)
```

**`TypeScript`**

```typescript title="TypeScript"
const entries = await client.lists.list("receive", "allow", { limit: 10 });
```

**`CLI`**

```bash title="CLI"
# записи из receive allowlist
agentinbox lists list \
  --direction receive \
  --type allow \
  --limit 10
```

### Создать запись

Добавить адрес или домен. Параметр `reason` необязателен и доступен для block-списков.

**`Python`**

```python title="Python"
# allow — reason не нужен
client.lists.create("receive", "allow", entry="partner@example.com")

# block — reason необязателен
client.lists.create("receive", "block", entry="spam@example.com", reason="spam")
```

**`TypeScript`**

```typescript title="TypeScript"
// allow — reason не нужен
await client.lists.create("receive", "allow", { entry: "partner@example.com" });

// block — reason необязателен
await client.lists.create("receive", "block", { entry: "spam@example.com", reason: "spam" });
```

**`CLI`**

```bash title="CLI"
# allow
agentinbox lists create \
  --direction receive \
  --type allow \
  --entry partner@example.com

# block — reason необязателен
agentinbox lists create \
  --direction receive \
  --type block \
  --entry spam@example.com \
  --reason spam
```

### Получить запись

Найти запись по email или домену.

**`Python`**

```python title="Python"
entry = client.lists.get("receive", "allow", entry="partner@example.com")
```

**`TypeScript`**

```typescript title="TypeScript"
const entry = await client.lists.get("receive", "allow", "partner@example.com");
```

**`CLI`**

```bash title="CLI"
# получить конкретную запись
agentinbox lists retrieve \
  --direction receive \
  --type allow \
  --entry partner@example.com
```

### Удалить запись

**`Python`**

```python title="Python"
client.lists.delete("receive", "allow", entry="partner@example.com")
```

**`TypeScript`**

```typescript title="TypeScript"
await client.lists.delete("receive", "allow", "partner@example.com");
```

**`CLI`**

```bash title="CLI"
# удалить запись
agentinbox lists delete \
  --direction receive \
  --type allow \
  --entry partner@example.com
```

### Списки уровня inbox

Те же операции для одного ящика.

**`Python`**

```python title="Python"
# Добавить в receive allowlist inbox
client.inboxes.lists.create(
    "inbox_id", "receive", "allow", entry="vip@example.com"
)

# Список записей inbox
entries = client.inboxes.lists.list("inbox_id", "receive", "allow")
```

**`TypeScript`**

```typescript title="TypeScript"
// Добавить в receive allowlist inbox
await client.inboxes.lists.create("inbox_id", "receive", "allow", {
  entry: "vip@example.com",
});

// Список записей inbox
const entries = await client.inboxes.lists.list("inbox_id", "receive", "allow");
```

**`CLI`**

```bash title="CLI"
# добавить в receive allowlist inbox
agentinbox inboxes:lists create \
  --inbox-id inbox_id \
  --direction receive \
  --type allow \
  --entry vip@example.com

# список записей inbox
agentinbox inboxes:lists list \
  --inbox-id inbox_id \
  --direction receive \
  --type allow
```

### Reply-списки

Кто может отвечать на исходящие письма ящика.

**`Python`**

```python title="Python"
# Разрешить ответы только с домена
client.lists.create("reply", "allow", entry="nobu.com")
```

**`TypeScript`**

```typescript title="TypeScript"
// Разрешить ответы только с домена
await client.lists.create("reply", "allow", { entry: "nobu.com" });
```

**`CLI`**

```bash title="CLI"
# только ответы с домена
agentinbox lists create \
  --direction reply \
  --type allow \
  --entry nobu.com
```

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

Скопируйте один из блоков ниже для полного контекста по API списков.

**`Python`**

```python title="Python"
"""
Agent Inbox Lists, copy into Cursor/Claude.

Filter emails by allow/block for send/receive/reply. 6 types: receive|send|reply x allow|block.
Lists can be scoped to org, pod, or inbox level.

API reference (org-level):
- lists.list(direction, type, limit?, page_token?)
- lists.create(direction, type, entry, reason?), reason only for block lists
- lists.get(direction, type, entry)
- lists.delete(direction, type, entry)

Pod-level: pods.lists.list(pod_id, direction, type, ...) and same for create/get/delete.
Inbox-level: inboxes.lists.list(inbox_id, direction, type, ...) and same for create/get/delete.

Entry: full email (user@domain.com) or domain (example.com).
Cascade: inbox > pod > org (most specific scope wins).
Reply lists: inbound replies (detected via In-Reply-To) check reply lists, not receive lists.
"""
from agentinbox import Agentinbox

client = Agentinbox(api_key="YOUR_API_KEY")

# Org-level lists
entries = client.lists.list("receive", "allow", limit=10)
client.lists.create("receive", "allow", entry="partner@example.com")
client.lists.create("receive", "block", entry="spam@example.com", reason="spam")
e = client.lists.get("receive", "allow", entry="partner@example.com")
client.lists.delete("receive", "allow", entry="partner@example.com")

# Reply lists
client.lists.create("reply", "allow", entry="nobu.com")

# Inbox-level lists
client.inboxes.lists.create("inbox_id", "receive", "allow", entry="vip@example.com")
inbox_entries = client.inboxes.lists.list("inbox_id", "receive", "allow")
```

**`TypeScript`**

```typescript title="TypeScript"
/**
 * Agent Inbox Lists, copy into Cursor/Claude.
 *
 * Filter emails by allow/block for send/receive/reply. 6 types: receive|send|reply x allow|block.
 * Lists can be scoped to org, pod, or inbox level.
 *
 * API reference (org-level):
 * - lists.list(direction, type, { limit?, pageToken? })
 * - lists.create(direction, type, { entry, reason? }) — reason only for block
 * - lists.get(direction, type, entry)
 * - lists.delete(direction, type, entry)
 *
 * Pod-level: pods.lists.list(podId, direction, type, ...) and same for create/get/delete.
 * Inbox-level: inboxes.lists.list(inboxId, direction, type, ...) and same for create/get/delete.
 *
 * Entry: full email or domain.
 * Cascade: inbox > pod > org (most specific scope wins).
 * Reply lists: inbound replies (detected via In-Reply-To) check reply lists, not receive lists.
 */
import { AgentinboxClient } from "agentinbox";

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

async function main() {
  // Org-level lists
  const entries = await client.lists.list("receive", "allow", { limit: 10 });
  await client.lists.create("receive", "allow", { entry: "partner@example.com" });
  await client.lists.create("receive", "block", { entry: "spam@example.com", reason: "spam" });
  const e = await client.lists.get("receive", "allow", "partner@example.com");
  await client.lists.delete("receive", "allow", "partner@example.com");

  // Reply lists
  await client.lists.create("reply", "allow", { entry: "nobu.com" });

  // Inbox-level lists
  await client.inboxes.lists.create("inbox_id", "receive", "allow", {
    entry: "vip@example.com",
  });
  const inboxEntries = await client.inboxes.lists.list(
    "inbox_id", "receive", "allow"
  );
}
main();
```