Сообщения | Agent Inbox | Документация

Что такое Message?

В экосистеме Agent Inbox Message — это представление обычного письма, ориентированное на API. Это структурированный объект со всем привычным: отправитель, получатели, тема и тело.

Каждое Message живёт внутри Thread, чтобы беседы оставались упорядоченными. При отправке нового Message создаётся новый Thread. При ответе новое Message добавляется в существующий Thread — как в обычной почтовой переписке.

В Agent Inbox удобно подключать людей к диалогам агента: в любое сообщение можно добавить реального человека в cc или bcc, чтобы построить сценарий «человек в контуре» для контроля, эскалаций или проверки качества.

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

С ресурсом Message можно работать по-разному: отправлять новые письма и просматривать историю переписки.

1. Инициализация клиента

Сначала инициализируйте клиент Agent Inbox с API-ключом — через него выполняются все вызовы API.

1 from agentinbox import Agentinbox
2 
3 client = Agentinbox(api_key="YOUR_API_KEY")

2. Отправка нового `Message`

Чтобы начать новую беседу, отправьте Message из одного из ваших ящиков. Будет создан новый Thread, а в ответ вернётся объект Message.

1 # You'll need an inbox ID to send from.
2 # Let's assume we have one:
3 
4 sent_message = client.inboxes.messages.send(
5 inbox_id = 'my_inbox@domain.com',
6 to = 'recipient@domain.com',
7 labels=[
8 "outreach",
9 "startup"
10 ],
11 subject="[YC S25] Founder Reachout ",
12 text="Hello, I'm Michael, and I'm a founder at Agent Inbox...",
13 html="<div dir=\"ltr\">Hello,<br /><br />I'm Michael, and I'm a founder at Agent Inbox..."
14 )
15 print(f"Message sent successfully with ID: {sent_message.message_id}")

Лимит получателей: при каждой отправке или ответе не более 50 получателей в сумме по полям to, cc и bcc. При превышении API вернёт ошибку.

3. Список `Messages` в `Inbox`

Можно получить список всех Messages в конкретном Inbox — удобно для истории переписки.

1 all_messages = client.inboxes.messages.list(inbox_id='my_inbox@agentinbox.space')
2 
3 print(f"Found {all_messages.count} messages in the inbox.")

4. Ответ на `Message`

Ответ на существующее Message добавляет новое Message в тот же Thread.

1 # Python example
2 reply = client.inboxes.messages.reply(
3     inbox_id='my_inbox@domain.com'
4     message_id='<abc123@agentinbox.space>',
5     text="Thanks for the referral!",
6     attachments=[
7         SendAttachment(
8             content="resume" # this would obviously be your resume content, refer to the attachment section of the core-concepts for more details
9         )
10     ]
11 )
12 
13 print(f"Reply sent successfully with ID: {reply.message_id}")

В ответе inbox_id — это ящик, с которого вы отправляете. В отличие от сценария send, здесь нужно явно указать один из потенциально многих Inboxes.

5. Получение `Message`

Детали конкретного Message запрашиваются по его ID вместе с inbox_id, к которому оно относится.

1 message = client.inboxes.messages.get(inbox_id = 'my_inbox@agentinbox.space', message_id = '<abc123@agentinbox.space>')
2 
3 print(f"Retrieved message with subject: {message.subject}")

При получении ответов и пересылок для только нового текста используйте extracted_text или extracted_html — цитируемая история отрезается автоматически.

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

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

1 """
2 Agent Inbox Messages — copy into Cursor/Claude.
3 
4 Setup: pip install agentinbox python-dotenv. Set AGENTINBOX_API_KEY in .env.
5 
6 API reference:
7 - messages.send(inbox_id, to, subject, text, html?, cc?, bcc?, reply_to?, labels?, attachments?)
8 - messages.list(inbox_id, limit?, page_token?, labels?)
9 - messages.get(inbox_id, message_id)
10 - messages.reply(inbox_id, message_id, text, html?, attachments?, reply_all?)
11 - messages.forward(inbox_id, message_id, to, subject?, text?, html?)
12 - messages.update(inbox_id, message_id, add_labels?, remove_labels?)
13 - messages.get_attachment(inbox_id, message_id, attachment_id)
14 - messages.get_raw(inbox_id, message_id)
15 
16 Reply content: use extracted_text/extracted_html for new content without quoted history.
17 Errors: SDK raises on 4xx/5xx. Rate limit: 429 with Retry-After.
18 """
19 import os
20 from dotenv import load_dotenv
21 from agentinbox import Agentinbox
22 
23 load_dotenv()
24 client = Agentinbox(api_key=os.getenv("AGENTINBOX_API_KEY"))
25 
26 inbox_id = "agent@agentinbox.space"
27 
28 # Send
29 sent = client.inboxes.messages.send(inbox_id, to="user@example.com", subject="Hi", text="Body", labels=["outreach"])
30 print(sent.message_id, sent.thread_id)
31 
32 # List, get
33 res = client.inboxes.messages.list(inbox_id, limit=10)
34 for msg in res.messages:
35     content = msg.extracted_text or msg.text
36 msg = client.inboxes.messages.get(inbox_id, res.messages[0].message_id)
37 
38 # Reply
39 reply = client.inboxes.messages.reply(inbox_id, msg.message_id, text="Thanks!")

Тело письма: HTML, текст и CSS

При отправке Message тело можно задать в двух форматах: text — простой текст, html — разметка со стилями.

text: обычная строка без форматирования. Запасной вариант для клиентов без HTML.
html: HTML-документ для оформления, цветов, шрифтов и изображений.

Рекомендация: всегда отправляйте и text, и html.

Зачем и текст, и HTML?

Современные клиенты чаще показывают HTML, но не все умеют его рендерить — текстовый вариант гарантирует читаемость. Кроме того, это заметно улучшает доставляемость.

Стилизация через CSS

Чтобы стилизовать HTML в Message, встраивайте CSS в тег <style> внутри <head> тела запроса — так надёжнее для Gmail, Outlook и Apple Mail.

Пример аккуратного заголовка письма в HTML:

Styled HTML Email Example

1 <html>
2   <head>
3     <meta charset="UTF-8">
4     <meta name="viewport" content="width=device-width, initial-scale=1.0">
5     <title>Your Agent Inbox Invoice</title>
6     <style>
7       body {
8         font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif;
9         line-height: 1.6;
10         color: #333;
11         max-width: 600px;
12         margin: 0 auto;
13         padding: 20px;
14         background-color: #f8f9fa;
15       }
16       .email-wrapper {
17         background: #ffffff;
18         border: 1px solid #e9ecef;
19         border-radius: 8px;
20         box-shadow: 0 4px 8px rgba(0, 0, 0, 0.05);
21         overflow: hidden;
22       }
23       .email-header {
24         background-color: #000000;
25         color: #ffffff;
26         padding: 24px;
27         text-align: center;
28       }
29       .email-header h1 {
30         margin: 0;
31         font-size: 24px;
32         font-weight: 600;
33       }
34       .email-content {
35         padding: 32px;
36       }
37       .greeting {
38         font-size: 18px;
39         font-weight: 500;
40         margin-bottom: 24px;
41       }
42       .main-message {
43         font-size: 16px;
44         margin-bottom: 24px;
45       }
46       .cta-button {
47         display: inline-block;
48         padding: 12px 24px;
49         background-color: #1a73e8;
50         color: #ffffff;
51         text-decoration: none;
52         border-radius: 6px;
53         font-weight: 500;
54         font-size: 16px;
55         margin-top: 8px;
56         margin-bottom: 24px;
57       }
58       .invoice-details {
59         background-color: #f8f9fa;
60         padding: 16px;
61         border-radius: 6px;
62         margin-bottom: 24px;
63         border: 1px solid #dee2e6;
64       }
65       .invoice-details p {
66         margin: 0;
67         font-size: 14px;
68       }
69       .invoice-details strong {
70         color: #000;
71       }
72       .signature {
73         margin-top: 24px;
74         font-size: 14px;
75         color: #555;
76       }
77       .email-footer {
78         text-align: center;
79         padding: 20px;
80         font-size: 12px;
81         color: #6c757d;
82       }
83       .email-footer a {
84         color: #1a73e8;
85         text-decoration: none;
86       }
87     </style>
88   </head>
89   <body>
90     <div class="email-wrapper">
91       <div class="email-header">
92         <h1>Agent Inbox</h1>
93       </div>
94       <div class="email-content">
95         <div class="greeting">Hi there,</div>
96         <div class="main-message">
97           Your invoice for the period of October 2025 is ready. We've automatically charged your saved payment method. Thank you for your business!
98         </div>
99 
100         <div class="invoice-details">
101           <p><strong>Invoice Number:</strong> INV-2025-10-0123</p>
102           <p><strong>Amount:</strong> $49.00</p>
103           <p><strong>Status:</strong> Paid</p>
104         </div>
105 
106         <a href="#" class="cta-button">View Full Invoice</a>
107 
108         <div class="signature">
109           Best regards,<br />
110           The Agent Inbox Team
111         </div>
112       </div>
113     </div>
114     <div class="email-footer">
115       <p>&copy; 2025 Agent Inbox, Inc. All Rights Reserved.</p>
116       <p><a href="#">Unsubscribe</a> | <a href="#">Billing Settings</a></p>
117     </div>
118   </body>
119 </html>

Замечание о наличии поля `text`

Поля text и preview у входящего Message берутся из MIME-части text/plain. Некоторые клиенты — в частности Gmail и Outlook — пересылают письма только в HTML без текстовой части. Тогда text и preview могут отсутствовать.

При обработке входящих сообщений считайте основным источником html, а text — опциональным.

Получение `Messages`

Периодический список Messages возможен, но для входящей почты агентам эффективнее вебхуки. Настроив endpoint, вы получаете уведомление сразу при новом Message и можете сразу реагировать.

Руководство: вебхуки

Как настроить вебхуки для обработки сообщений в реальном времени.

Пометка сообщений как прочитанных

В Agent Inbox нет отдельного endpoint «пометить прочитанным» — состояние читается через метки. Так обычно избегают повторной обработки одних и тех же писем агентом.

1 # Mark a message as read after processing
2 client.inboxes.messages.update(
3     inbox_id="agent@agentinbox.space",
4     message_id=msg.message_id,
5     add_labels=["read"],
6     remove_labels=["unread"]
7 )
8 
9 # Only fetch unread messages
10 unread = client.inboxes.messages.list(
11     inbox_id="agent@agentinbox.space",
12     labels=["unread"]
13 )

Как не обрабатывать дубликаты

Если агент использует вебхуки, сразу после обработки помечайте сообщение как read (или processed). После перезапуска или повторной обработки фильтруйте по labels=["unread"], чтобы пропускать уже обработанные письма.