---
title: "Create or Reconnect a Shared Mailbox"
method: POST
path: "/v2/mailboxes"
tags: ["mailboxes"]
---

# Create or Reconnect a Shared Mailbox

`POST /v2/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/mailboxes`
- Auth: HTTP bearer

Mints an application-permission Nylas grant via /v3/connect/custom using the
organization's configured Microsoft credential, and creates the shared
mailbox. Requires admin consent to already be in place.

Idempotent per email: if a shared mailbox for this address already exists,
its grant is **re-minted** (a fresh grant replaces the old one in place) —
this is how an application mailbox "reconnects", since it has no delegated
user to re-authenticate.

## Request body

- CreateSharedMailboxRequest: Create an application-permission shared mailbox. Mints a Nylas grant via /v3/connect/custom using the org's configured Microsoft credential. Requires admin consent to be in place.
  - `email` string, email, required: The account's email.
  - `name` string, nullable: Email owner's name.
  - `is_centralized_inbox` boolean: Whether this sender is a centralized inbox that accepts net-new inbound emails for routing

## Response `201`

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/3b5ab941f918?raw)