Inbox

The Inbox is a ticketing system for inbound communications. It creates a clear separation between two types of interaction:

Asynchronous conversations — Direct chat with an assistant (via the browser, widget, or API). These do not go through the inbox.
Synchronous communications — Inbound email and similar channels. These are routed through the inbox, where the assistant triages and responds.

Think of it like a colleague’s inbox: you can chat with them directly (async), or send them an email that lands in their inbox (sync). The inbox gives both the assistant and human admins visibility into external communications.

How It Works

When an email arrives via a configured Postmark channel:

An inbox item is created with the email subject, sender, and message content
The assistant is automatically notified and uses its inbox tools to read and respond
The assistant’s reply is sent back as an email to the sender
Follow-up replies from the sender are threaded into the same inbox item

Real-time channels like Telegram and Slack continue to create direct conversations — they bypass the inbox.

Viewing the Inbox

There are three ways to access the inbox:

Sidebar — The Inbox link in the sidebar shows all inbox items across assistants, with an unread count badge.
From the Assistants page — Each assistant card has an Inbox button that shows only that assistant’s items.
Direct link — Navigate to /inbox/ for the global view or /inbox/<assistant_id> for a specific assistant.

Inbox Item Lifecycle

Each inbox item has a status:

Status	Description
Open	New item, not yet addressed
In Progress	The assistant (or admin) has started responding
Closed	Resolved — with optional resolution note
Snoozed	Temporarily hidden until a specified date

When a reply is sent (by the assistant or admin), the status automatically moves from Open to In Progress. If a closed item receives a new reply from the sender, it is automatically reopened.

Priority Levels

Priority	Description
Low	Non-urgent, can wait
Normal	Standard priority (default)
High	Should be addressed soon
Urgent	Needs immediate attention

Priority can be set by the assistant (using update_inbox_item) or changed by an admin from the detail page.

Thread View

Click on an inbox item to see the full message thread. The thread shows:

Inbound messages — From the sender, with any attachments
Assistant replies — Sent by the assistant via email
Internal notes — Added by admins or when closing with a resolution note

Each message shows the sender, timestamp, and any file attachments with download links.

Replying from the UI

Admins can reply to inbox items directly from the detail page. The reply is:

Saved as an assistant message in the thread
Sent via the assistant’s email channel to the sender
Threaded with the original conversation using email headers

Attachments

The inbox supports attachments in both directions:

Inbound — File attachments on incoming emails are saved and displayed as download links in the thread.
Outbound — The assistant can attach files (from execute_code results) to replies using deliverable IDs.

This means someone can email the assistant a spreadsheet, the assistant can process it with code execution, and send back a modified version — all within the inbox thread.

Filtering

The inbox list supports filtering by:

Assistant — Dropdown to show items for a specific assistant
Status tabs — Active (open + in progress), Closed, or All

Auto-Processing

When a new inbox item arrives, the assistant is automatically triggered to process it. The assistant receives context about the sender, subject, and message content, along with instructions to use its inbox tools. This means most inbound emails are triaged and responded to without human intervention.

If the assistant needs help or the item requires human judgment, it can leave the item open for admin review.

Agent Tools

The assistant has six inbox tools available:

Tool	Description
list_inbox	List inbox items with optional status filter
get_inbox_item	Read the full message thread of an inbox item
reply_to_inbox	Send a reply via email, with optional file attachments
close_inbox_item	Close an item, optionally with a resolution note
update_inbox_item	Update status, priority, or tags
snooze_inbox_item	Snooze until a future date

These tools are registered in the Inbox category and can be enabled or disabled per assistant from the Tools tab.

Creating Todos from Inbox Items

The assistant can create todos linked to inbox items. For example, after processing an email request, the assistant might create a follow-up todo:

create_todo(
    title="Send updated invoice to customer",
    source_type="inbox",
    source_id=42
)

The todo will display a source link back to the originating inbox item.

Technical Details

Email threading — Each inbox item has a unique reply_token (UUID). When the assistant replies, the reply-to address includes this token (e.g., bot+<token>@in.example.com). When the sender replies, the webhook handler checks inbox item reply tokens before conversation reply tokens, routing the message back to the correct thread.

Webhook flow — The webhook handler at /webhooks/channels/<plugin>/inbound now has three routing paths:

Inbox reply — If reply_token matches an InboxItem, add an InboxMessage and enqueue an AgentRun with source_type="inbox_reply" on the inbox_item:<id> lane
Conversation reply — If reply_token matches a Conversation, continue the existing flow
New message — For email channels, create an InboxItem and enqueue an AgentRun with source_type="inbox_item"; for real-time channels (Telegram, Slack), create a direct conversation

Runtime integration — Inbox executions go through the unified AgentRunRuntime. The inbox_item:<id> lane key serializes activity per item: a flurry of replies on the same item runs sequentially, while different items proceed in parallel. The runtime owns lifecycle, heartbeats, cancellation, checkpoints, and resume — see Agent Runs for operator-facing controls. Two source types map to two handlers on AgentService:

inbox_item — handle_inbox_item_run. Materialises a conversation for a brand-new inbox item and runs the agent loop with the system message describing the item.
inbox_reply — handle_inbox_reply_run. Continues the linked conversation when one exists, otherwise falls through to the inbox-item handler’s path.

Channel scope — Only email-type channels route through the inbox. Channels in the _CHANNEL_USER_FIELDS mapping (currently Telegram) maintain their existing direct-conversation flow, since they are inherently real-time and conversational.

Deduplication — The webhook handler checks message IDs against both Message.metadata_json and InboxMessage.metadata_json to prevent duplicate processing when webhooks are retried.