> ## Documentation Index
> Fetch the complete documentation index at: https://help.withallo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Create, update and delete personal inboxes, and list the conversations of an inbox

The Inboxes API manages **personal inboxes**. An inbox is a saved view over one or more Allo lines, optionally narrowed to phone-menu options (for example "Website FR, option 2"), with its own filters and notification setting. It is the same inbox you see in the inbox switcher of the Allo app.

## Key concepts

**Personal** - an inbox belongs to one user. The API acts on the caller's inboxes. Another user's inbox returns `404` with code `INBOX_NOT_FOUND`.

**Teammate inboxes** - admins and managers can act on a teammate's inboxes with `user_id`: in the JSON body to create or update, as a query parameter to list or delete. The inbox is owned by the teammate and shows in the teammate's switcher. Every source line must be accessible to the teammate. Without admin or manager rights, the request returns `403` with code `FORBIDDEN`.

With `user_id`, an admin or manager only reaches what sits in a workspace they manage. The list shows only the teammate's inboxes with at least one source in such a workspace, and only those sources. An inbox outside it returns `404` on update or delete. Replacing `sources` keeps the teammate's lines from other workspaces. Deleting an inbox that also holds lines from another workspace returns `403` with code `FORBIDDEN`. A teammate inbox must keep at least one line of the admin's workspace, otherwise the request returns `400` with code `INVALID_INBOX_SOURCE`.

**Sources** - each source is an Allo line (`allo_number`) plus optional `conditions`. A source with an empty `conditions` list covers every conversation on the line. A `MENU_BRANCH` condition matches paths through the line's phone menus. A `MENU_OPTION` condition matches keys of one menu.

**Several options on one line** - each line appears once in `sources`. To cover several menu options of the same line, put all their paths in the `branches` of a single `MENU_BRANCH` condition. Two sources with the same `allo_number` return `400` with code `INVALID_INBOX_SOURCE`.

**Menu conditions need an engine-routed line** - a menu condition is accepted only on a line whose [menu options](https://help.withallo.com/en/v2/api-reference/inboxes/list-menu-options.md) list is not empty, and only with paths from that list. On any other line, use a whole-line source with empty `conditions`.

**Right after create** - listing the conversations of an inbox created a moment ago can briefly return `404` with code `INBOX_NOT_FOUND` and `retryable: true`. Retry once. A `404` on update or delete is not retryable.

**Suggestions first** - [Get inbox suggestions](https://help.withallo.com/en/v2/api-reference/inboxes/get-inbox-suggestions.md) returns sources ranked from the caller's recent calls and texts. Each suggestion carries a `source` to put in `sources` as is, so you never need menu node IDs. Use [List menu options](https://help.withallo.com/en/v2/api-reference/inboxes/list-menu-options.md) only to build a custom branch: each option carries a ready `condition`.

**Listing conversations** - pass `inbox_id` to [List conversations](https://help.withallo.com/en/v2/api-reference/conversations/list-conversations.md) instead of `allo_number`. The results hold conversations from several lines, each row with its own `allo_number`. The inbox's sources and saved filters apply, but not the app's Needs action and Mine tabs. "Unread only" is not saved on an inbox: pass the `unread` query parameter on List conversations.

**Limits** - up to 50 inboxes per user, 100 sources per inbox, 10 conditions per source, and 60 menu steps per inbox. A `MENU_BRANCH` takes 1 to 20 branches of 1 to 6 steps. Creating a 51st inbox returns `400` with code `INBOX_LIMIT_REACHED`. A name over 80 characters, an emoji over 16, or more than 100 sources or 10 conditions per source returns `400` with code `INVALID_REQUEST_BODY`, and `field_errors` names each field.

**Scopes** - reading needs `INBOXES_READ`, writing needs `INBOXES_WRITE`. A key without the scope gets `403` with code `API_KEY_INSUFFICIENT_SCOPE`.

## Endpoints

> **[List inboxes](https://help.withallo.com/en/v2/api-reference/inboxes/list-inboxes.md)**
>
> Your inboxes, or a teammate's

> **[Get inbox suggestions](https://help.withallo.com/en/v2/api-reference/inboxes/get-inbox-suggestions.md)**
>
> Ready-made sources ranked from recent activity

> **[List menu options](https://help.withallo.com/en/v2/api-reference/inboxes/list-menu-options.md)**
>
> The phone-menu options of a line, flattened

> **[Create inbox](https://help.withallo.com/en/v2/api-reference/inboxes/create-inbox.md)**
>
> Create an inbox for yourself or a teammate

> **[Update inbox](https://help.withallo.com/en/v2/api-reference/inboxes/update-inbox.md)**
>
> Rename, change sources or filters, mute or unmute

> **[Delete inbox](https://help.withallo.com/en/v2/api-reference/inboxes/delete-inbox.md)**
>
> Delete an inbox


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.