---
title: "Update a Mailbox"
method: PATCH
path: "/v2/mailboxes/{mailbox_id}"
tags: ["mailboxes"]
---

# Update a Mailbox

`PATCH /v2/mailboxes/{mailbox_id}`

## 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}`
- Auth: HTTP bearer

Updates editable fields: display name, signature, reply-to, and the
shared / centralized-inbox flags. Connection state (provider, grant,
permission type) is set by the auth flow, not here.

Permissions: the owner can update their own delegated mailbox; shared
mailboxes can be updated by any org member; centralized inboxes require
mailbox configuration rights.

## Path parameters

- `mailbox_id` string, required

## Request body

- UpdateMailboxRequest: Update editable mailbox fields.
  - `name` string, nullable: Email owner's name.
  - `signature_html` string, nullable: Email signature html.
  - `is_centralized_inbox` boolean, nullable: Whether this sender is a centralized inbox that accepts net-new inbound emails for routing
  - `is_shared` boolean, nullable: Whether this email sender should be shared with the entire organization
  - `reply_to` string, nullable: This account's default reply-to
  - `send_as` string, email, nullable: Alias to send outgoing mail from. Must be one of the mailbox's provider-verified email_aliases. Pass null to revert to the primary address.

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