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

# Assign mailbox

> Moves the conversation to a mailbox or category

<Info>
  **Endpoint** · `POST /conversation/actions`
</Info>

Moves the conversation to a mailbox or a category. Exactly **one** of
`mailbox` | `category`, never both.

**Fields**

* `mailbox` — `{ name }` of the mailbox. Provide this **or** `category`, never both.
* `category` — `{ name }` of the category. Provide this **or** `mailbox`, never both.

```jsonc theme={null}
{
  "type": "assign_mailbox",
  "mailbox": { "name": "Ventas" }
}
{
  "type": "assign_mailbox",
  "category": { "name": "Soporte" }
}
```

In a list, this object goes in the `actions` array of a `POST /conversation/actions` — see [Assembling an action list](/en/action-groups/overview#assembling-an-action-list).

## Executable example

An `assign_mailbox` on a conversation identified by phone and channel. Exactly
**one** of `mailbox` or `category`, never both — and each mode behaves
differently:

* **`mailbox`** — assigns the conversation to the exact mailbox you name.
* **`category`** — you don't pick a mailbox: the system balances the load and
  assigns the conversation to the mailbox with the **fewest pending chats**
  within that category (handy for auto-distributing across a team). The category
  must have at least one mailbox configured.

### Request

<CodeGroup>
  ```bash Mailbox theme={null}
  curl -X POST "https://app.1to1.ai/api/v1/public/{slug}/conversation/actions" \
    -H "Authorization: Bearer sk_1to1_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "conversation": {
        "phone": "+5215512345678",
        "channel": "ch_7A9K2M4Q"
      },
      "actions": [
        {
          "type": "assign_mailbox",
          "mailbox": { "name": "Ventas" }
        }
      ]
    }'
  ```

  ```bash Category theme={null}
  curl -X POST "https://app.1to1.ai/api/v1/public/{slug}/conversation/actions" \
    -H "Authorization: Bearer sk_1to1_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "conversation": {
        "phone": "+5215512345678",
        "channel": "ch_7A9K2M4Q"
      },
      "actions": [
        {
          "type": "assign_mailbox",
          "category": { "name": "Soporte" }
        }
      ]
    }'
  ```
</CodeGroup>

### Response

`202 Accepted` — the group was accepted and runs in the **background**. The
per-action result does not travel in the response (query it later — see [How it runs](/en/action-groups/overview#how-it-runs)).

```json theme={null}
{
  "status": "processing",
  "actions_accepted": 1
}
```

<ResponseField name="status" type="string">
  Always `processing`: confirms the group was accepted and is running.
</ResponseField>

<ResponseField name="actions_accepted" type="integer">
  How many actions in the array were **admitted** for execution — not how many
  succeeded.
</ResponseField>