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

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

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

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

Python

from flask import Flask, request
from agentinbox import Agentinbox
app = Flask(__name__)
client = Agentinbox()
@app.route("/webhooks", methods=["POST"])
def handle_webhook():
    payload = request.json
    
    if payload["event_type"] == "message.received":
        message = payload["message"]
        
        # Your agent processes the email here
        reply_text = your_agent.process(message)
        
        # Reply in the same thread
        client.inboxes.messages.reply(
            inbox_id=message["inbox_id"],
            message_id=message["message_id"],
            text=reply_text
        )
    
    return "OK", 200

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

Python

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

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

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

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

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

Python

import asyncio
from agentinbox import AsyncAgentinbox, Subscribe, Subscribed, MessageReceivedEvent
client = AsyncAgentinbox()
async def main():
    async with client.websockets.connect() as socket:
        await socket.send_subscribe(Subscribe(
            inbox_ids=["agent@agentinbox.space"]
        ))
        async for event in socket:
            if isinstance(event, Subscribed):
                print(f"Subscribed to: {event.inbox_ids}")
            elif isinstance(event, MessageReceivedEvent):
                print(f"New email from: {event.message.from_}")
                print(f"Subject: {event.message.subject}")
asyncio.run(main())

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

Python

from agentinbox import Agentinbox, Subscribe, MessageReceivedEvent
client = Agentinbox()
with client.websockets.connect() as socket:
    socket.send_subscribe(Subscribe(
        inbox_ids=["agent@agentinbox.space"]
    ))
    for event in socket:
        if isinstance(event, MessageReceivedEvent):
            print(f"New email from: {event.message.from_}")

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

Что выбрать?

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

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