Как обрабатывать входящие письма?

Webhooks и WebSockets для приёма почты.

Два основных способа обработки входящих писем — под разные сценарии.

1. Webhooks (для продакшена)

Укажите URL — Agent Inbox отправит POST при каждом письме. Надёжный вариант для продакшена.

Python
1from flask import Flask, request
2from agentinbox import Agentinbox
3
4app = Flask(__name__)
5client = Agentinbox()
6
7@app.route("/webhooks", methods=["POST"])
8def handle_webhook():
9 payload = request.json
10
11 if payload["event_type"] == "message.received":
12 message = payload["message"]
13
14 # Your agent processes the email here
15 reply_text = your_agent.process(message)
16
17 # Reply in the same thread
18 client.inboxes.messages.reply(
19 inbox_id=message["inbox_id"],
20 message_id=message["message_id"],
21 text=reply_text
22 )
23
24 return "OK", 200

Регистрация webhook:

Python
1client.webhooks.create(
2 url="https://your-domain.ngrok-free.app/webhooks",
3 events=["message.received"],
4)

Сразу отвечайте 200 OK и обрабатывайте событие в фоне. Долгий ответ приведёт к повторным доставкам. Отфильтруйте message.sent, чтобы агент не отвечал сам себе по кругу.

Для локальной разработки — ngrok. Полная инструкция: Настройка webhooks.

2. WebSockets (без публичного URL)

Поток событий по постоянному соединению. Не нужен публичный URL — удобно для локальной разработки и десктоп-агентов.

Python
1import asyncio
2from agentinbox import AsyncAgentinbox, Subscribe, Subscribed, MessageReceivedEvent
3
4client = AsyncAgentinbox()
5
6async def main():
7 async with client.websockets.connect() as socket:
8 await socket.send_subscribe(Subscribe(
9 inbox_ids=["agent@agentinbox.space"]
10 ))
11
12 async for event in socket:
13 if isinstance(event, Subscribed):
14 print(f"Subscribed to: {event.inbox_ids}")
15 elif isinstance(event, MessageReceivedEvent):
16 print(f"New email from: {event.message.from_}")
17 print(f"Subject: {event.message.subject}")
18
19asyncio.run(main())

Синхронный клиент:

Python
1from agentinbox import Agentinbox, Subscribe, MessageReceivedEvent
2
3client = Agentinbox()
4
5with client.websockets.connect() as socket:
6 socket.send_subscribe(Subscribe(
7 inbox_ids=["agent@agentinbox.space"]
8 ))
9
10 for event in socket:
11 if isinstance(event, MessageReceivedEvent):
12 print(f"New email from: {event.message.from_}")

Подробнее: WebSockets.

Что выбрать?

СпособКогдаПубличный URL?Реальное время?
WebhooksПродакшенДаДа
WebSocketsЛокально, десктопНетДа

В продакшене чаще webhooks — надёжно и хорошо для serverless. Если нужны события без публичного endpoint — WebSockets.