> 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. # Ящики (инбоксы) > Узнайте, как ящики Agent Inbox работают как масштабируемые почтовые аккаунты с приоритетом API для ваших агентов. ## Что такое ящик (Inbox)? Привычно думать об ограничениях классической почты — один ящик на человека. Это в прошлом. `Inbox` — это полноценный программно доступный ресурс API, переработанный под масштаб AI-агентов. Представьте что-то вроде аккаунта Gmail или Outlook, но изначально построенного вокруг API. У каждого `Inbox` свой уникальный адрес электронной почты; это главный ресурс, через который агент отправляет и получает письма и получает полноценную идентичность в интернете. В отличие от классических провайдеров, рассчитанных на людей, ящики Agent Inbox масштабируются горизонтально. Вы можете по запросу создавать десятки, сотни или тысячи `Inboxes` для своих агентов. > **Tip** > > Между прочим: вместо 1000 писем из одного `Inbox` отправка по 10 писем из 100 > `Inboxes` улучшает доставляемость. Подробнее об оптимизации — [здесь](/email-deliverability) ### Иерархия Agent Inbox Как показано на схеме ниже, ваша `organization` — контейвер верхнего уровня для всех ресурсов. Внутри неё вы создаёте множество `Inboxes`, у каждого свои `Threads`, `Messages` и `Attachments`, чтобы управлять большим парком агентов без лишней суеты. ![Иерархия организации Agent Inbox](/_fern-files/_img/800085ec8545f404e194c8c6e463be1677715204ac5705be777fa95ace0e6d26.webp) #### Организация Ваша `organization` — сущность самого высокого уровня. Она объединяет все ваши `Inboxes`, `Domains` и API-ключи, чтобы управлять всем из одного места. #### Ящик (Inbox) `Inbox` — это один масштабируемый «почтовый аккаунт» для агента. В организации можно создать тысячи `Inboxes`, у каждого — свой уникальный адрес. #### Цепочка (Thread) `Thread` — одна беседа. В ней сгруппированы все ответы и пересылки, связанные с исходным письмом, чтобы переписка оставалась упорядоченной. #### Сообщение (Message) `Message` — отдельное письмо: содержимое, отправитель, получатели и метаданные или `Attachments`. В любой момент можно добавить людей в копию, чтобы оставить «человека в контуре». #### Вложение (Attachment) `Attachment` — файл, отправляемый вместе с `Message`. Вложения из входящих `Messages` можно программно получать и скачивать. ## Основные возможности В Agent Inbox `Inbox` — это ресурс API: доступны стандартные CRUD-операции. Ниже — ключевые сценарии управления `Inboxes`. ```python from agentinbox import Agentinbox # Initialize the client client = Agentinbox(api_key="YOUR_API_KEY") # --- Create an Inbox --- # Creates a new inbox with a default agentinbox.space domain new_inbox = client.inboxes.create() print(f"Created Inbox: {new_inbox.inbox_id}") # --- Retrieve an Inbox --- # Gets a specific inbox by its ID retrieved_inbox = client.inboxes.get(inbox_id = 'my_name@domain.com') print(f"Retrieved Inbox: {retrieved_inbox.inbox_id}") # --- List Inboxes --- # Lists all inboxes in your organization all_inboxes = client.inboxes.list() print(f"Total Inboxes: {all_inboxes.count}") ``` **`TypeScript`** ```typescript title="TypeScript" import { AgentinboxClient } from "agentinbox"; // Initialize the client const client = new AgentinboxClient({ apiKey: "YOUR_API_KEY" }); // --- Create an Inbox --- // Creates a new inbox with a default agentinbox.space domain const newInbox = await client.inboxes.create({ username: "docs-testing", domain: "domain.com", displayName: "Docs Tester", }); console.log(`Created Inbox: ${newInbox.id}`); // --- Retrieve an Inbox --- // Gets a specific inbox by its ID const inboxId = newInbox.id; const retrievedInbox = await client.inboxes.get(inboxId); console.log(`Retrieved Inbox: ${retrievedInbox.inbox_id}`); // --- List Inboxes --- // Lists all inboxes in your organization const allInboxes = await client.inboxes.list(); console.log(`Total Inboxes: ${allInboxes.count}`); ``` **`CLI`** ```bash title="CLI" # create an inbox agentinbox inboxes create \ --username docs-testing \ --domain domain.com \ --display-name "Docs Tester" # retrieve an inbox agentinbox inboxes retrieve --inbox-id my_name@domain.com # list all inboxes agentinbox inboxes list ``` > **Tip** > > При создании `Inbox` поля `username` и `domain` необязательны. Если их не > указать, Agent Inbox сгенерирует уникальный адрес на нашем домене по умолчанию. > Подробнее — в [руководстве по управлению доменами](/managing-domains). ## API-ключи с областью ящика Можно создавать API-ключи, ограниченные одним ящиком. Такой ключ видит только цепочки, сообщения и черновики этого ящика. Это удобно, когда агенту или интеграции нужен минимум доступа. ```python # Create a key scoped to one inbox key = client.inboxes.api_keys.create( new_inbox.inbox_id, name="support-agent-key" ) # The full key is only returned once print(key.api_key) ``` **`TypeScript`** ```typescript title="TypeScript" const key = await client.inboxes.apiKeys.create(newInbox.id, { name: "support-agent-key", }); // The full key is only returned once console.log(key.apiKey); ``` Подробнее о ключах с ограниченной областью — в [руководстве по мультитенантности](/multi-tenancy#inbox-scoped-keys). ## Копировать в Cursor / Claude Скопируйте один из блоков ниже в Cursor или Claude, чтобы за один раз передать полное описание API ящиков. **`Python`** ```python title="Python" """ Agent Inbox — Inboxes API — copy into Cursor/Claude. Setup: pip install agentinbox python-dotenv. Set AGENTINBOX_API_KEY in .env. API reference: - inboxes.create(username?, domain?, display_name?, client_id?) — client_id for idempotent retries - inboxes.get(inbox_id) - inboxes.list(limit?, page_token?) - inboxes.update(inbox_id, display_name) - inboxes.delete(inbox_id) - inboxes.api_keys.create(inbox_id, name) — inbox-scoped key - inboxes.api_keys.list(inbox_id) - inboxes.api_keys.delete(inbox_id, api_key_id) Errors: SDK raises on 4xx/5xx. Rate limit: 429 with Retry-After. """ import os from dotenv import load_dotenv from agentinbox import Agentinbox load_dotenv() client = Agentinbox(api_key=os.getenv("AGENTINBOX_API_KEY")) # Create (client_id for idempotent retries) inbox = client.inboxes.create(client_id="my-inbox-v1") # Get, list retrieved = client.inboxes.get(inbox.inbox_id) all_inboxes = client.inboxes.list(limit=20) print(f"Total: {all_inboxes.count}") ``` **`TypeScript`** ```typescript title="TypeScript" /** * Agent Inbox — Inboxes API — copy into Cursor/Claude. * * Setup: npm install agentinbox dotenv. Set AGENTINBOX_API_KEY in .env. * * API reference: * - inboxes.create({ username?, domain?, displayName?, clientId? }) * - inboxes.get(inboxId) * - inboxes.list({ limit?, pageToken? }) * - inboxes.update(inboxId, { displayName }) * - inboxes.delete(inboxId) * - inboxes.apiKeys.create(inboxId, { name }) — inbox-scoped key * - inboxes.apiKeys.list(inboxId) * - inboxes.apiKeys.delete(inboxId, apiKeyId) * * Errors: SDK throws on 4xx/5xx. Rate limit: 429 with Retry-After. */ import { AgentinboxClient } from "agentinbox"; import "dotenv/config"; const client = new AgentinboxClient({ apiKey: process.env.AGENTINBOX_API_KEY! }); async function main() { const inbox = await client.inboxes.create({ clientId: "my-inbox-v1" }); const retrieved = await client.inboxes.get(inbox.inboxId); const allInboxes = await client.inboxes.list({ limit: 20 }); console.log("Total:", allInboxes.count); } main(); ```