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

# Update workspace mailbox

> Changes the localpart of the workspace outbound mailbox, the address all agents send
from, renaming both the workspace setting and its system endpoint together. Admin
only. The localpart must be lowercase alphanumerics with '.' or '-' separators (max
63 chars) and is rejected if it is reserved or already used by a custom inbox; the
mailbox never auto-replies and that behavior is not configurable here.



## OpenAPI

````yaml PATCH /v1/api/email/workspace-mailbox
openapi: 3.1.0
info:
  title: HQ API
  description: >-
    Public HTTP API for HQ. Authenticate with a Personal Access Token
    (`Authorization: Bearer hq_pat_...`) for server-side integrations, or an
    OAuth 2.1 authorization-code + PKCE flow for browser apps acting on a user's
    behalf. Both grant from the same resource:action scope vocabulary; an
    endpoint's required scope is listed under its `security`.
  license:
    name: Apache-2.0
    identifier: Apache-2.0
  version: 1.0.0
servers:
  - url: https://api.hq.zone
    description: HQ API (production)
security: []
tags:
  - name: me
    description: The signed-in user's own account
  - name: conversations
    description: Conversations and their messages
  - name: documents
    description: The content-addressed documents library
  - name: schedules
    description: Scheduled prompts and recurring tasks
  - name: agents
    description: Agents, their skills and integrations
  - name: memory
    description: What the assistant remembers (L5 governance)
  - name: tokens
    description: Personal Access Token management
  - name: billing
    description: Usage and billing
  - name: notifications
    description: In-app notification center
  - name: admin
    description: Workspace administration
  - name: integrations
    description: Workspace integrations (Slack, MCP, skills)
  - name: onboarding
    description: New-workspace onboarding wizard
  - name: auth
    description: Sign-in, sessions, and OAuth
paths:
  /v1/api/email/workspace-mailbox:
    patch:
      tags:
        - admin
      summary: Update workspace mailbox
      description: >-
        Changes the localpart of the workspace outbound mailbox, the address all
        agents send

        from, renaming both the workspace setting and its system endpoint
        together. Admin

        only. The localpart must be lowercase alphanumerics with '.' or '-'
        separators (max

        63 chars) and is rejected if it is reserved or already used by a custom
        inbox; the

        mailbox never auto-replies and that behavior is not configurable here.
      operationId: update_mailbox
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkspaceMailboxPatch'
        required: true
      responses:
        '200':
          description: Workspace mailbox localpart updated
          content:
            application/json:
              schema: {}
        '400':
          description: Invalid or reserved localpart
      security:
        - bearer_pat:
            - admin
        - oauth2:
            - admin
components:
  schemas:
    WorkspaceMailboxPatch:
      type: object
      description: >-
        PATCH the workspace outbound mailbox: change its localpart (the address
        all

        agents send from). The localpart edit renames
        `tenants.outbound_mailbox_localpart`

        AND the system endpoint's localpart in one transaction.


        The workspace mailbox is fire-and-notify ONLY: it never auto-replies. A

        reply to it always files to the Review queue + notifies the initiator,
        so

        `reply_policy` is fixed to `never_reply` and is NOT configurable here
        (an

        address that *answers* mail is a custom inbox, created via
        create_endpoint).

        The only knob is the address.
      properties:
        court_intake_enabled:
          type:
            - boolean
            - 'null'
          description: |-
            Court-document intake on/off for the team mailbox (the address court
            secure-mail typically lands on). Omitted = keep current.
            See docs/court-document-intake.md.
        court_secure_mail_password:
          type:
            - string
            - 'null'
          description: >-
            Secure-mail password for the court portal. WRITE-ONLY: vault-sealed
            when

            non-empty, never echoed back. Omitted/empty = keep the stored
            password.
        localpart:
          type:
            - string
            - 'null'
  securitySchemes:
    bearer_pat:
      type: http
      scheme: bearer
      bearerFormat: hq_pat
      description: 'Personal Access Token. Send as `Authorization: Bearer hq_pat_...`.'
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://app.hq.zone/v1/oauth/authorize
          tokenUrl: https://api.hq.zone/v1/oauth/token
          refreshUrl: https://api.hq.zone/v1/oauth/token
          scopes:
            admin: Administer the workspace (users, settings, integrations)
            agents:read: View the agents in your workspace
            agents:write: Create and configure agents
            billing:read: View usage and billing information
            conversations:read: Read your conversations and their messages
            conversations:write: Start conversations and send messages on your behalf
            documents:read: Read your documents library
            documents:write: Upload and manage documents in your library
            memory:read: Read what the assistant remembers about you
            memory:write: Correct or delete what the assistant remembers
            schedules:read: View your scheduled tasks
            schedules:write: Create and manage scheduled tasks
            tables:read: Read your tables and their rows
            tables:write: Create tables and add, edit, or delete rows

````