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

# Pods

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

## Что такое pod?

Pod — изолированная сущность между вашей **организацией** и **inbox**, которая помогает сегментировать и организовать почтовую инфраструктуру в многотенантных приложениях. Если вы делаете сервис с почтой для своих клиентов, pod — ключ к изоляции их ресурсов.

### Иерархия

```
Organization (ваш бизнес)
    └── Pod (клиент A)
        ├── Inbox 1
        ├── Inbox 2
        └── Domain 1
    └── Pod (клиент B)
        ├── Inbox 3
        ├── Inbox 4
        └── Domain 2
```

**Organization**: аккаунт Agent Inbox вашей компании

* У вас одна организация, представляющая бизнес

**Pod**: каждый из ваших клиентов

* Создавайте один pod на клиента/тенанта в своей системе
* Pod дают полную изоляцию данных между клиентами
* Все ресурсы (inbox, домены, треды, черновики) можно привязать к pod

**Inbox**: отдельные почтовые ящики внутри pod

* У клиента может быть несколько inbox в одном pod
* Вы сами обеспечиваете ресурсы для каждого клиента

## Зачем нужны pod?

### Мультитенантность

Pod позволяют предлагать инфраструктуру Agent Inbox своим клиентам при строгой изоляции данных. Типичные сценарии:

**Платформы SaaS/агентства**: отдельный pod на каждого клиента — у каждого свой изолированный почтовый контур.

**White-label почта**: сервис под вашим брендом; у каждого конечного пользователя свой pod и изоляция данных.

**Платформы ИИ-агентов**: отдельный pod под агента с его задачами — со своими inbox и доменами.

## Как устроены pod

### Жизненный цикл

На стороне API при создании ресурсов происходит следующее.

* При регистрации у вас автоматически создаётся `Default Pod`; все ресурсы — `Inboxes` или `Domains` — привязываются к этому `Default Pod`.
* Удалить `Pod`, у которого ещё есть дочерние ресурсы, нельзя. Сначала удалите связанные `Inboxes` и `Domains`, затем `Pod`.

### Что можно делать с pod

#### Создание ресурсов

Внутри pod можно создавать:

* **Inboxes (Ящики)**
* **Domains (Домены)**

> **Note**
>
> Сейчас домен может быть привязан либо к одному pod, либо ко всем pod сразу. Нельзя привязать домен к нескольким, но не ко всем pod.

> **Tip**
>
> Указывайте `client_id` при создании `Pod`, чтобы однозначно сопоставлять pod с вашими сущностями. Тогда не нужна отдельная таблица соответствия ваших `organization_id` и наших `pod_id` — задайте `client_id` как ваш внутренний идентификатор и обращайтесь к ресурсу по нему.

Эти ресурсы автоматически связываются с pod и наследуют гарантии изоляции.

#### Список ресурсов

Следующие ресурсы можно **получать в разрезе** pod:

* **Inboxes** (`GET /pods/{pod_id}/inboxes`) — все inbox в pod
* **Threads** (`GET /pods/{pod_id}/threads`) — все переписки по всем inbox pod
* **Drafts** (`GET /pods/{pod_id}/drafts`) — все черновики по всем inbox pod
* **Domains** (`GET /pods/{pod_id}/domains`) — все пользовательские домены pod

Так вы получаете единую картину активности в «рабочем пространстве» клиента — удобно для сценариев вроде:

* «Покажи все непрочитанные письма клиента X» (используйте и метки!)
* «Список всех тредов по всем командным inbox клиента Y»
* «Все ожидающие черновики клиента Z»

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

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

**`Python`**

```python title="Python"
"""
Agent Inbox Pods — copy into Cursor/Claude. Multi-tenant isolation.

API reference:
- pods.create(client_id?) — client_id for idempotent mapping to your tenant IDs
- pods.get(pod_id), pods.list(limit?, page_token?), pods.delete(pod_id)
- pods.inboxes.list(pod_id, ...), pods.inboxes.create(pod_id, ...), pods.inboxes.delete(pod_id, inbox_id)
- pods.domains.list(pod_id, ...), pods.domains.create(pod_id, ...), pods.domains.delete(pod_id, domain_id)
- pods.threads.list(pod_id, ...), pods.drafts.list(pod_id, ...)

Delete order: inboxes + domains first, then pod. Deleting inbox/domain cascades to messages/threads.
"""
from agentinbox import Agentinbox

client = Agentinbox(api_key="YOUR_API_KEY")

pod = client.pods.create(client_id="tenant-acme-1")
inboxes = client.pods.inboxes.list(pod.pod_id)
inbox = client.pods.inboxes.create(pod.pod_id, username="support", display_name="Support")
threads = client.pods.threads.list(pod.pod_id, limit=20)
```

**`TypeScript`**

```typescript title="TypeScript"
/**
 * Agent Inbox Pods — copy into Cursor/Claude. Multi-tenant isolation.
 *
 * API reference:
 * - pods.create({ clientId? })
 * - pods.get(podId), pods.list({ limit?, pageToken? }), pods.delete(podId)
 * - pods.inboxes.list(podId, ...), pods.inboxes.create(podId, ...), pods.inboxes.delete(podId, inboxId)
 * - pods.domains.list(podId, ...), pods.domains.create(podId, ...), pods.domains.delete(podId, domainId)
 * - pods.threads.list(podId, ...), pods.drafts.list(podId, ...)
 *
 * Delete order: inboxes + domains first, then pod.
 */
import { AgentinboxClient } from "agentinbox";

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

async function main() {
  const pod = await client.pods.create({ clientId: "tenant-acme-1" });
  const inboxes = await client.pods.inboxes.list(pod.podId);
  const inbox = await client.pods.inboxes.create(pod.podId, { username: "support", displayName: "Support" });
  const threads = await client.pods.threads.list(pod.podId, { limit: 20 });
}
main();
```

## Важные моменты

### Ограничения при удалении pod

> **Warning**
>
> **Критично**: нельзя удалить pod, пока к нему привязаны ресурсы.
> Сначала удалите все inbox и домены внутри pod, затем сам pod.

Это защита от случайной потери данных. Правильный порядок:

```typescript
// Не сработает, если в pod ещё есть ресурсы
await client.pods.delete(podId);

// Правильно: сначала очистка
async function offboardCustomer(podId: string) {
  // 1. Удалить все inbox
  const inboxRes = await client.inboxes.list(podId);
  for (const inbox of inboxRes.inboxes) {
    await client.inboxes.delete(inbox.inbox_id);
  }

  // 2. Удалить все домены
  const domainRes = await client.domains.list({ podId });
  for (const domain of domainRes.domains) {
    await client.domains.delete(domain.domain_id);
  }

  // 3. Теперь можно удалить pod
  await client.pods.delete(podId);
}
```

> **Info**
>
> При удалении inbox или домена связанные данные (сообщения, треды, черновики) очищаются автоматически. Удалять треды и сообщения по одному не нужно.

**Что НЕ изолировано уровнем pod:**

* API-ключи уровня организации (доступ ко всем ресурсам во всех pod). Используйте [API-ключи с областью pod](/multi-tenancy#pod-scoped-keys), чтобы ограничить доступ одним pod, или [API-ключи с областью inbox](/multi-tenancy#inbox-scoped-keys) — одним inbox.

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

### Сценарий 1: мультитенантный SaaS

У каждой компании на платформе свой pod:

```typescript
// Рабочее пространство клиента A
Pod: "Acme Corp"
├── Inbox: support@acme.com
├── Inbox: sales@acme.com
└── Domain: acme.com

// Рабочее пространство клиента B
Pod: "TechStart Inc"
├── Inbox: hello@techstart.io
├── Inbox: team@techstart.io
└── Domain: techstart.io
```

### Сценарий 2: агентство и клиенты

У каждого клиента изолированный pod:

```typescript
// Клиент 1
Pod: "Client - Retail Co"
├── Inbox: info@retailco.com
└── Domain: retailco.com

// Клиент 2
Pod: "Client - FinTech"
├── Inbox: support@fintech.ai
└── Domain: fintech.ai
```

### Сценарий 3: платформа ИИ-агентов

У каждого агента свой pod и выделенная почта:

```typescript
// Агент 1: поддержка
Pod: "Support-Agent"
├── Inbox: support@mycompany.com
├── Inbox: help@mycompany.com
└── Inbox: tickets@mycompany.com

// Агент 2: продажи
Pod: "Sales-Agent"
├── Inbox: sales@mycompany.com
├── Inbox: outreach@mycompany.com
└── Inbox: leads@mycompany.com

// Агент 3: маркетинг
Pod: "Marketing-Agent"
├── Inbox: newsletter@mycompany.com
├── Inbox: campaigns@mycompany.com
└── Inbox: events@mycompany.com
```

## FAQ

#### Могут ли inbox из разных pod переписываться друг с другом?

Да. Inbox в разных pod обмениваются почтой как обычные адреса. Pod дают организационную изоляцию, а не сетевую.

#### Можно ли перенести inbox из одного pod в другой?

Нет, перенос между pod не поддерживается. Создайте новый inbox в нужном pod.

#### Сколько pod можно создать?

Жёсткого лимита нет — создавайте столько, сколько нужно под клиентов.

#### Обязательно ли использовать pod?

Необязательно, но для многотенантных приложений настоятельно рекомендуется. Если вы управляете почтой только своей организации, можно работать напрямую с inbox без отдельных pod.

#### Можно ли задать свои разрешения на уровне pod?

Да. Можно создать API-ключ с областью одного pod или ключ с областью одного inbox внутри pod. Подробнее — в [руководстве по мультитенантности](/multi-tenancy#scoped-api-keys).

## Дальше

* Узнайте про [Inboxes](/inboxes) и создание ящиков внутри pod
* Изучите [Domains](/custom-domains) для своих доменов под pod