Skip to main content
Every operation below exists in the app, as an MCP tool for your AI agent, and in the Inbox API.

List threads

Threads come pinned first, then by newest activity. The filters match the inbox tabs: The answer also carries the counters of the tabs: open, unread, needsAttention, needsTakeover, unassigned, snoozed, closed and, when the call acts as a user, mine.

Search inside messages

To find a thread by what was written (not by who wrote it), search the messages: text, email subject, sender name or address. The HTML of emails without a text part is searched too. Results are threads, newest match first, and each one shows the matching message as lastMessage, so you can see why it matched. Without fromDate the search covers the last 180 days. Narrow it with channel, direction (inbound = written by the contact) and a date range.

Read a thread

Reading returns the thread and its most recent messages, oldest to newest, every channel together:
  • text is always plain text, also for emails that only have HTML (ask for includeHtml to get the HTML too).
  • WhatsApp media come as media.url (image, audio, video, document), email files as attachments.
  • Messages you sent carry their delivery status, failureReason and seenAt.
The default is the latest 30 messages (up to 100). When olderMessages is true, read further back with beforeMessageId set to the first messageId you got.
Reading never marks a thread as read. Mark it explicitly, as below.

Update a thread

Updates act as the user of the key or connection and send nothing to the contact.