---
title: "Set Mailbox Business Units"
method: PUT
path: "/v2/mailboxes/{mailbox_id}/business-units"
tags: ["mailboxes"]
---

# Set Mailbox Business Units

`PUT /v2/mailboxes/{mailbox_id}/business-units`

## Request

- Base URL: `https://api.stuut.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.stuut.ai/v2/mailboxes/{mailbox_id}/business-units`
- Auth: HTTP bearer

Assigns a shared mailbox to one or more business units. This is a full
replacement — the provided list becomes the complete set of assignments.

- Pass one or more BU IDs to scope the mailbox to those BUs.
- Pass an empty list (`[]`) to remove all scoping, making the mailbox
  visible to all users in the organisation (the default behaviour).

Users scoped to a business unit will only see collections-inbox triage
threads from mailboxes assigned to their business unit (or unscoped
mailboxes). For a hybrid mailbox (Nylas + a paired SendGrid sender), the
paired sender is scoped identically since it's what actually sends mail.
Requires organisation admin.

## Path parameters

- `mailbox_id` string, required

## Request body

- SetMailboxBusinessUnitsRequest: Set business unit scoping for a shared mailbox. Passing an empty list removes all scoping, making the mailbox visible to all users in the organisation (the default unscoped behaviour).
  - `business_unit_ids` string[]: IDs of business units to scope this mailbox to.

## Response `200`

Successful Response

- Mailbox
  - `created_at` string, date-time, required
  - `modified_at` string, date-time, nullable, required
  - `id` string, required
  - `email` string, required: The account's email.
  - `email_aliases` string[], nullable, required
  - `send_as` string, email, nullable, required: Alias designated as the From address for outgoing mail. One of email_aliases, or null to send from the primary address.
  - `name` string, nullable, required: Email owner's name.
  - `provider` string, nullable, required: Mail provider — 'microsoft', 'google', 'imap', 'sendgrid', etc.
  - `permission_type` 'delegated' | 'application', required: How a mailbox was authenticated.
  - `is_shared` boolean, required: Whether this email sender should be shared with the entire organization
  - `is_centralized_inbox` boolean, required: Whether this sender is a centralized inbox that accepts net-new inbound emails for routing
  - `status` 'connected' | 'expired' | 'disconnected', required: Computed connection health.
  - `archived_at` string, date-time, nullable, required: When the mailbox was disconnected from Stuut. Kept around for historical email attribution rather than deleted.
  - `user_id` string, nullable, required: Owning user. NULL for shared mailboxes.
  - `signature_html` string, nullable, required: Email signature html.
  - `reply_to` string, required: This account's default reply-to
  - `business_unit_ids` string[], required: Business units this shared mailbox is scoped to. Empty means visible to all users in the organisation.
  - `object` string, required: String representing the object's type. Objects of the same type share the same value.
  - `uses_legacy_entra_app` boolean, required: True when this Microsoft mailbox's grant was minted against the legacy Entra app and must be re-authenticated to migrate onto the current app.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/stuut/apis/stuut-api.md) - [All operations](https://skmtc.dev/stuut/apis/stuut-api/llms.txt) - [OpenAPI document](https://skmtc.dev/stuut/apis/stuut-api/revisions/ff0ad16a55ff?raw)