---
title: "Handle Delegated OAuth Callback"
method: POST
path: "/v2/mailboxes/auth/callback"
tags: ["mailboxes"]
---

# Handle Delegated OAuth Callback

`POST /v2/mailboxes/auth/callback`

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

Exchanges the authorization code for a grant, then creates the mailbox
for the authenticated user — or refreshes an existing one if this is a
re-auth (same grant email already connected).

## Request body

- AuthCallbackRequest
  - `code` string, required: Authorization code returned by Nylas after sign-in.
  - `redirect_uri` string, required: Must match the redirect_uri used to generate the auth URL.
  - `state` string, required: The signed state token from the auth URL, echoed back by Nylas.

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