Skip to main content
GET
Get Agent Inbox
Agents can be reached on inbound channels: email (when an email trigger is configured) and WhatsApp (on a user’s personal Omni). This endpoint lists those conversations - the agent’s inbox - newest first, with filters for channel, date range and title text. It is agent-wide: every sender’s conversation with this agent, not just the caller’s. For an agent’s full task history across all sources, use Get Agent Tasks instead.

Path Parameters

string
required
Unique identifier of the agent (UUID format)

Query Parameters

string
Comma-separated channels to include: email, whatsapp. Defaults to every channel enabled on the agent. Asking for a channel the agent does not have returns 400.
string
Only conversations created at or after this ISO date/datetime. A bare date (2026-08-01) covers that whole UTC day.
string
Only conversations created at or before this ISO date/datetime. A bare date covers the whole day.
string
Case-insensitive text matched against conversation titles.
integer
default:20
Maximum conversations to return (1-50).

Response

array
Inbound conversations, newest first
array
Inbound channels enabled on this agent. An empty array means the agent has no inbox at all - clients should hide the surface rather than show an empty list.
integer
Number of matching conversations before limit was applied

Example Requests

Everything in the inbox

Search one channel

A date range

Example Response

Use Cases

  • Inbox view: render everything people sent an agent, across channels
  • Lookup: find the conversation a specific person or subject started
  • Triage: filter by date range to review what arrived while nobody was watching

Notes

  • Only top-level conversations are listed; sub-tasks spawned inside a conversation are excluded
  • Each channel is queried separately and the results merged, so a channel that is temporarily unavailable degrades the list rather than failing it - the request only errors when every requested channel fails
  • sender is null when the conversation came from an identity with no email on file
  • The agent itself can list the same conversations in chat, so “what emails did you get?” is answered from real data rather than guessed

See Also

Authorizations

x-api-key
string
header
required

API Key for authentication

Path Parameters

agent_id
string
required

Query Parameters

source
string
default:""

Comma-separated channels to include (email, whatsapp). Defaults to every channel enabled on the agent.

from_date
string
default:""

ISO date/datetime - only conversations created at or after it (a bare date covers the whole UTC day).

to_date
string
default:""

ISO date/datetime - only conversations created at or before it.

q
string
default:""

Case-insensitive text matched against conversation titles.

limit
integer
default:20

Max conversations to return.

Required range: 1 <= x <= 50

Response

Successful Response

The agent's inbound inbox, filtered.

items
InboxConversation · object[]
sources_enabled
string[]

Inbox channels enabled on this agent; empty means no inbox at all.

total
integer
default:0

Matches before the limit cap was applied.