Ящики (инбоксы)

Основа идентичности и коммуникации вашего агента.

Что такое ящик (Inbox)?

Привычно думать об ограничениях классической почты — один ящик на человека. Это в прошлом.

Inbox — это полноценный программно доступный ресурс API, переработанный под масштаб AI-агентов.

Представьте что-то вроде аккаунта Gmail или Outlook, но изначально построенного вокруг API. У каждого Inbox свой уникальный адрес электронной почты; это главный ресурс, через который агент отправляет и получает письма и получает полноценную идентичность в интернете.

В отличие от классических провайдеров, рассчитанных на людей, ящики Agent Inbox масштабируются горизонтально. Вы можете по запросу создавать десятки, сотни или тысячи Inboxes для своих агентов.

Между прочим: вместо 1000 писем из одного Inbox отправка по 10 писем из 100 Inboxes улучшает доставляемость. Подробнее об оптимизации — здесь

Иерархия Agent Inbox

Как показано на схеме ниже, ваша organization — контейвер верхнего уровня для всех ресурсов. Внутри неё вы создаёте множество Inboxes, у каждого свои Threads, Messages и Attachments, чтобы управлять большим парком агентов без лишней суеты.

Иерархия организации Agent Inbox
1

Организация

Ваша organization — сущность самого высокого уровня. Она объединяет все ваши Inboxes, Domains и API-ключи, чтобы управлять всем из одного места.

2

Ящик (Inbox)

Inbox — это один масштабируемый «почтовый аккаунт» для агента. В организации можно создать тысячи Inboxes, у каждого — свой уникальный адрес.

3

Цепочка (Thread)

Thread — одна беседа. В ней сгруппированы все ответы и пересылки, связанные с исходным письмом, чтобы переписка оставалась упорядоченной.

4

Сообщение (Message)

Message — отдельное письмо: содержимое, отправитель, получатели и метаданные или Attachments. В любой момент можно добавить людей в копию, чтобы оставить «человека в контуре».

5

Вложение (Attachment)

Attachment — файл, отправляемый вместе с Message. Вложения из входящих Messages можно программно получать и скачивать.

Основные возможности

В Agent Inbox Inbox — это ресурс API: доступны стандартные CRUD-операции. Ниже — ключевые сценарии управления Inboxes.

1from agentinbox import Agentinbox
2
3# Initialize the client
4client = Agentinbox(api_key="YOUR_API_KEY")
5
6# --- Create an Inbox ---
7# Creates a new inbox with a default agentinbox.space domain
8new_inbox = client.inboxes.create()
9print(f"Created Inbox: {new_inbox.inbox_id}")
10
11# --- Retrieve an Inbox ---
12# Gets a specific inbox by its ID
13retrieved_inbox = client.inboxes.get(inbox_id = 'my_name@domain.com')
14print(f"Retrieved Inbox: {retrieved_inbox.inbox_id}")
15
16# --- List Inboxes ---
17# Lists all inboxes in your organization
18all_inboxes = client.inboxes.list()
19
20print(f"Total Inboxes: {all_inboxes.count}")

При создании Inbox поля username и domain необязательны. Если их не указать, Agent Inbox сгенерирует уникальный адрес на нашем домене по умолчанию. Подробнее — в руководстве по управлению доменами.

API-ключи с областью ящика

Можно создавать API-ключи, ограниченные одним ящиком. Такой ключ видит только цепочки, сообщения и черновики этого ящика. Это удобно, когда агенту или интеграции нужен минимум доступа.

1# Create a key scoped to one inbox
2key = client.inboxes.api_keys.create(
3 new_inbox.inbox_id,
4 name="support-agent-key"
5)
6
7# The full key is only returned once
8print(key.api_key)

Подробнее о ключах с ограниченной областью — в руководстве по мультитенантности.

Копировать в Cursor / Claude

Скопируйте один из блоков ниже в Cursor или Claude, чтобы за один раз передать полное описание API ящиков.

1"""
2Agent Inbox — Inboxes API — copy into Cursor/Claude.
3
4Setup: pip install agentinbox python-dotenv. Set AGENTINBOX_API_KEY in .env.
5
6API reference:
7- inboxes.create(username?, domain?, display_name?, client_id?) — client_id for idempotent retries
8- inboxes.get(inbox_id)
9- inboxes.list(limit?, page_token?)
10- inboxes.update(inbox_id, display_name)
11- inboxes.delete(inbox_id)
12- inboxes.api_keys.create(inbox_id, name) — inbox-scoped key
13- inboxes.api_keys.list(inbox_id)
14- inboxes.api_keys.delete(inbox_id, api_key_id)
15
16Errors: SDK raises on 4xx/5xx. Rate limit: 429 with Retry-After.
17"""
18import os
19from dotenv import load_dotenv
20from agentinbox import Agentinbox
21
22load_dotenv()
23client = Agentinbox(api_key=os.getenv("AGENTINBOX_API_KEY"))
24
25# Create (client_id for idempotent retries)
26inbox = client.inboxes.create(client_id="my-inbox-v1")
27
28# Get, list
29retrieved = client.inboxes.get(inbox.inbox_id)
30all_inboxes = client.inboxes.list(limit=20)
31print(f"Total: {all_inboxes.count}")