Skip to main content
Endpoint · GET /mailbox-categories
Read-only endpoint: it returns information and changes nothing. It is not sent inside the actions array — you call it directly.
Lists the active mailboxes of the business in alphabetical order, each one with its category and the channel it belongs to. This is the catalog you use to discover which mailbox or which category to move a conversation to with the assign_mailbox action: the name returned here is exactly the value that action expects.
The path is called mailbox-categories for historical reasons, but what it returns are mailboxes, not categories. Each mailbox’s category comes in the category field of every item.
The response is paginated with an opaque cursor: while has_more is true, repeat the call passing the previous page’s next_cursor in ?cursor=. Cursors are not shared across different endpoints, even though the format looks the same. Parameters Every query parameter is optional; with none of them you get the first page of the full catalog. The business slug goes in the path and is required.
  • search — case-insensitive substring of the mailbox name. The asterisk * works as a wildcard; % and _ are matched literally.
  • category — returns only the mailboxes in this category, by full name and case-insensitive. Accepts * as a wildcard. Mailboxes with no category are excluded, and a non-existent category returns an empty page, not an error.
  • channel — returns only the mailboxes of this channel, by its public key. This is not a pattern filter: the key is compared exactly against its canonical form —case-insensitive— and * is not a wildcard. A non-existent, partial or *-containing key returns 404 CHANNEL_NOT_FOUND.
  • cursor — opaque cursor returned by the previous page in next_cursor. Omit it to request the first page.
  • limit — mailboxes per page. Default 30, maximum 100.

​
Response

  • name — mailbox name. This is what you pass as mailbox in assign_mailbox.
  • category — category the mailbox belongs to, or null if it has none. Only the default mailbox of each channel can come back as null; those are always assigned by mailbox.
  • channel — public key of the channel the mailbox belongs to. A mailbox lives in a single channel, so this field tells you which conversations it can be used on.
  • next_cursor — cursor for the next page; null when has_more is false.
  • has_more — whether there are more results after this page.
Errors

​
Example

This call is a read: it does not create, move or modify any conversation. It only fetches the mailbox catalog so you know which name to use later in an action.
With the name of a mailbox from this response you can already build the Assign mailbox action, which is the one that actually moves the conversation. If instead of the exact mailbox you pass the category from that same response, the platform balances the load and picks the least busy mailbox in the category.