---
title: "Set Business Unit Mailboxes"
method: PUT
path: "/v2/business-units/{business_unit_id}/mailboxes"
tags: ["business-units"]
---

# Set Business Unit Mailboxes

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

## 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/business-units/{business_unit_id}/mailboxes`
- Auth: HTTP bearer

Update which shared mailboxes are scoped to this business unit, and return the resulting
mailboxes. The list is the complete set for THIS business unit only — a mailbox also scoped to
other business units keeps those other assignments; only its membership in this one is added
or removed.

- Pass one or more mailbox IDs to scope those shared mailboxes to this business unit.
- Pass an empty list (`[]`) to remove this business unit from every mailbox it was scoped to.

Only shared mailboxes can be scoped — a personal mailbox is always visible to its owner
regardless of business unit, so assigning one here would have no effect. A hybrid mailbox's
paired SendGrid sender (which isn't itself a selectable shared mailbox) is kept scoped
identically, since it's what actually sends mail for a hybrid sender. Requires organization
admin.

## Path parameters

- `business_unit_id` string, required

## Request body

- SetBusinessUnitMailboxesRequest: Set which shared mailboxes are scoped to a business unit. Full replacement for this business unit only — a mailbox also scoped to other business units keeps those other assignments; only its membership in this one is added or removed. Passing an empty list removes this business unit from every mailbox it was scoped to.
  - `mailbox_ids` string[]: IDs of the shared mailboxes that should be scoped to this business unit.

## 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)