> ## Documentation Index
> Fetch the complete documentation index at: https://sendmux.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Update a mailbox

> Updates any combination of display_name, quota_bytes, and send_scope on a mailbox. The display_name and send_scope changes land in a single transaction; quota_bytes is applied afterwards because it also updates external state on our mail platform. Quota can only be set to 1073741824 (1 GB), 5368709120 (5 GB), or 53687091200 (50 GB), and cannot be shrunk below the mailbox's current usage.

For optimistic concurrency, send `If-Match: <etag>` using the ETag from a prior GET. A mismatched `If-Match` returns `409 conflict` (the server's ETag is echoed back so you can decide whether to re-fetch). Responses carry the new ETag so chained edits can pipeline without a re-GET.



## OpenAPI

````yaml /openapi-app.json patch /mailboxes/{public_id}
openapi: 3.1.0
info:
  description: Programmatic access to your Qubrics email infrastructure.
  title: Qubrics API
  version: 1.0.0
servers:
  - description: API v1
    url: https://app.qubrics.com/api/v1
security:
  - bearerAuth: []
  - oauth2: []
paths:
  /mailboxes/{public_id}:
    patch:
      tags:
        - Mailboxes
      summary: Update a mailbox
      description: >-
        Updates any combination of display_name, quota_bytes, and send_scope on
        a mailbox. The display_name and send_scope changes land in a single
        transaction; quota_bytes is applied afterwards because it also updates
        external state on our mail platform. Quota can only be set to 1073741824
        (1 GB), 5368709120 (5 GB), or 53687091200 (50 GB), and cannot be shrunk
        below the mailbox's current usage.


        For optimistic concurrency, send `If-Match: <etag>` using the ETag from
        a prior GET. A mismatched `If-Match` returns `409 conflict` (the
        server's ETag is echoed back so you can decide whether to re-fetch).
        Responses carry the new ETag so chained edits can pipeline without a
        re-GET.
      operationId: managementUpdateMailbox
      parameters:
        - in: path
          name: public_id
          required: true
          schema:
            description: Mailbox public ID
            type: string
        - in: header
          name: If-Match
          required: false
          schema:
            description: >-
              Weak ETag from a prior GET. Reject with 409 conflict when the
              server's current ETag differs.
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateMailboxBody'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailboxItemResponse'
          description: Updated mailbox
          headers:
            ETag:
              description: Weak ETag for the post-update resource.
              schema:
                type: string
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Invalid request body
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Mailbox not found
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: '`If-Match` ETag does not match the server''s current version.'
        '413':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Request body too large
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: >-
            Validation error — unsupported quota tier, quota below current
            usage, or cross-tenant send_scope reference
      security:
        - bearerAuth: []
        - oauth2:
            - mailbox.admin.manage
components:
  schemas:
    UpdateMailboxBody:
      additionalProperties: false
      properties:
        display_name:
          description: Replace the display name; send null to clear it.
          maxLength: 254
          minLength: 1
          type:
            - string
            - 'null'
        quota_bytes:
          description: >-
            Storage quota in bytes. Allowed values: 1073741824 (1 GB),
            5368709120 (5 GB), 53687091200 (50 GB).
          example: 5368709120
          minimum: 1
          type: integer
        send_scope:
          additionalProperties: false
          description: Replace outbound routing restrictions.
          properties:
            group_public_ids:
              description: >-
                Delivery group public IDs allowed for sending when type is
                `group`.
              items:
                maxLength: 128
                minLength: 1
                type: string
              type: array
            provider_public_ids:
              description: >-
                Provider public IDs allowed for sending when type is
                `providers`.
              items:
                maxLength: 128
                minLength: 1
                type: string
              type: array
            type:
              description: >-
                Outbound routing strategy. Use `providers` with
                provider_public_ids, or `group` with group_public_ids.
              enum:
                - all
                - providers
                - group
              type: string
          required:
            - type
          type: object
      type: object
    MailboxItemResponse:
      allOf:
        - $ref: '#/components/schemas/SuccessEnvelope'
        - properties:
            data:
              $ref: '#/components/schemas/Mailbox'
            meta:
              $ref: '#/components/schemas/ResponseMeta'
          required:
            - data
          type: object
      unevaluatedProperties: false
    ApiError:
      additionalProperties: false
      properties:
        error:
          additionalProperties: false
          properties:
            code:
              description: Machine-readable error code
              enum:
                - invalid_parameter
                - missing_parameter
                - authentication_required
                - insufficient_permissions
                - not_found
                - conflict
                - limit_exceeded
                - idempotency_conflict
                - payload_too_large
                - validation_error
                - rate_limit_exceeded
                - service_unavailable
                - internal_error
              example: invalid_parameter
              type: string
            doc_url:
              description: Link to relevant documentation
              type: string
            errors:
              description: >-
                Accumulated per-field issues for validation errors. Only present
                on 400/422 responses.
              items:
                $ref: '#/components/schemas/ApiErrorDetail'
              type: array
            message:
              description: Human-readable error description
              type: string
            param:
              description: The parameter that caused the error
              type: string
            retryable:
              description: >-
                Whether the caller may safely retry this request. 4xx are
                typically false (except 429); 5xx are typically true.
              example: false
              type: boolean
          required:
            - code
            - message
            - retryable
          type: object
        meta:
          additionalProperties: false
          properties:
            request_id:
              example: req_clxxxxxxxxxxxxxxxxxxxxxxxxx
              type: string
          required:
            - request_id
          type: object
        ok:
          enum:
            - false
          type: boolean
      required:
        - ok
        - error
        - meta
      type: object
    SuccessEnvelope:
      properties:
        meta:
          additionalProperties: {}
          properties: {}
          type: object
        ok:
          enum:
            - true
          type: boolean
      required:
        - ok
        - meta
      type: object
    Mailbox:
      additionalProperties: false
      properties:
        created_at:
          description: ISO 8601 creation timestamp
          type: string
        display_name:
          description: Optional display name shown in outbound From headers
          type:
            - string
            - 'null'
        email:
          description: Mailbox email address (lowercase)
          example: agent@acme.com
          type: string
        id:
          description: Public ID
          example: mbx_clxxxxxxxxxxxxxxxxxxxxxxxxx
          type: string
        quota_bytes:
          description: >-
            Storage quota in bytes. Current writable tiers are 1 GB, 5 GB, and
            50 GB.
          type:
            - integer
            - 'null'
        send_scope:
          $ref: '#/components/schemas/MailboxSendScope'
        status:
          description: active | suspended | deleted
          example: active
          type: string
      required:
        - id
        - email
        - display_name
        - quota_bytes
        - send_scope
        - status
        - created_at
      type: object
    ResponseMeta:
      additionalProperties: false
      properties:
        request_id:
          example: req_clxxxxxxxxxxxxxxxxxxxxxxxxx
          type: string
      required:
        - request_id
      type: object
    ApiErrorDetail:
      additionalProperties: false
      properties:
        code:
          description: >-
            Machine-readable issue code from the validator (e.g. zod issue
            code).
          example: invalid_string
          type: string
        field:
          description: Dot-path of the offending request field.
          example: recipient.email
          type: string
        message:
          description: Human-readable issue description.
          type: string
      required:
        - field
        - code
        - message
      type: object
    MailboxSendScope:
      additionalProperties: false
      properties:
        group_public_ids:
          description: Delivery group public IDs (only when type=group)
          items:
            type: string
          type: array
        provider_public_ids:
          description: Provider public IDs (only when type=providers)
          items:
            type: string
          type: array
        type:
          description: >-
            Outbound routing strategy. `all` lets the mailbox use any
            team-configured provider; `providers` restricts to the listed
            provider IDs; `group` routes via a delivery group.
          enum:
            - all
            - providers
            - group
          type: string
      required:
        - type
      type:
        - object
        - 'null'
  securitySchemes:
    bearerAuth:
      bearerFormat: API Key
      description: >-
        Qubrics API key. Use a root API key for Management API routes, or a
        mailbox credential for Mailbox API routes. Obtain keys from the
        dashboard under API Keys.
      scheme: bearer
      type: http
    oauth2:
      description: >-
        Use the authorisation-code flow with S256 PKCE and
        resource=https://qubrics.com/api. The user selects the team, API access
        and mailboxes during consent. OAuth access tokens authenticate HTTP API
        requests; use separate credentials for SMTP and IMAP.
      flows:
        authorizationCode:
          authorizationUrl: https://app.qubrics.com/oauth/authorize
          refreshUrl: https://app.qubrics.com/oauth/token
          scopes:
            analytics.*: All analytics operations
            analytics.read: View key usage analytics and verification logs
            billing.*: All billing operations
            billing.auto_topup: Configure auto top-up settings
            billing.read: View balance, transactions, invoices
            billing.topup: Purchase balance top-ups
            calendar.read: Read calendars and events in this mailbox
            calendar.write: >-
              Create calendars and create, edit and delete events in this
              mailbox
            domain.*: All domain operations
            domain.create: Add sending domains
            domain.delete: Remove domains
            domain.read: List/view domains and DNS status
            domain.verify: Trigger domain verification
            email.receive: Authorise email reception
            email.send: Send email through the HTTP API
            key.*: All key management operations
            key.create: Create new API keys (both root and mailbox)
            key.read: List/view API keys and their metadata
            key.revoke: Revoke API keys
            key.rotate: Rotate API keys
            logs.*: All log operations
            logs.read: View delivery logs
            mailbox.admin.*: All mailbox admin operations
            mailbox.admin.create: Create mailboxes (admin-level)
            mailbox.admin.delete: Delete mailboxes (admin-level)
            mailbox.admin.manage: Manage all mailbox settings
            mailbox.admin.read: List/view mailboxes (admin-level)
            mailbox.drafts.write: Create and edit saved mailbox drafts
            mailbox.read: Read mailbox contents (folders, messages)
            mailbox.settings.update: Update own mailbox settings (signature, auto-reply)
            provider.*: All provider operations
            provider.create: Add email provider accounts (Google, Microsoft, SMTP)
            provider.delete: Remove provider accounts
            provider.read: List/view provider accounts and connection status
            provider.update: Update provider settings, refresh tokens
            routing.*: All routing operations
            routing.create: Create delivery groups
            routing.delete: Remove delivery groups
            routing.read: List/view delivery groups and routing rules
            routing.update: Update delivery group configuration
            team.*: All team operations
            team.members.invite: Invite team members
            team.members.remove: Remove team members
            team.members.roles: Change member roles
            team.read: View team settings and members
            team.update: Update team settings
            webhook.*: All webhook operations
            webhook.create: Create webhook subscriptions
            webhook.delete: Delete webhook subscriptions
            webhook.manage: Rotate signing secret + send test events
            webhook.read: List/view webhook subscriptions
            webhook.update: Update webhook URL, event types, enabled flag
          tokenUrl: https://app.qubrics.com/oauth/token
      type: oauth2

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.