Ящики (инбоксы) | Agent Inbox

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

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

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

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

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

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

Иерархия Agent Inbox

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

Организация

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

Ящик (Inbox)

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

Цепочка (Thread)

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

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

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

Вложение (Attachment)

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

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

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

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}")

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

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

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

# 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)

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

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

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

"""
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}")