> ## 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 email endpoint

> Updates the configurable behavior of an inbound email endpoint and returns the
refreshed endpoint with counters. Admin only and scoped to the caller's workspace.
Omitted fields keep their current values, supplying allow_patterns replaces the
allowlist wholesale, and the localpart and kind cannot be changed. The system
workspace mailbox cannot be edited here (400), and an unknown or cross-workspace id
returns 404.



## OpenAPI

````yaml PATCH /v1/api/email/endpoints/{id}
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/endpoints/{id}:
    patch:
      tags:
        - admin
      summary: Update email endpoint
      description: >-
        Updates the configurable behavior of an inbound email endpoint and
        returns the

        refreshed endpoint with counters. Admin only and scoped to the caller's
        workspace.

        Omitted fields keep their current values, supplying allow_patterns
        replaces the

        allowlist wholesale, and the localpart and kind cannot be changed. The
        system

        workspace mailbox cannot be edited here (400), and an unknown or
        cross-workspace id

        returns 404.
      operationId: update_endpoint
      parameters:
        - name: id
          in: path
          description: Endpoint id
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfigPatch'
        required: true
      responses:
        '200':
          description: Endpoint updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EndpointJson'
        '400':
          description: Invalid config, or the system workspace mailbox can't be edited here
        '404':
          description: Not found
      security:
        - bearer_pat:
            - admin
        - oauth2:
            - admin
components:
  schemas:
    ConfigPatch:
      type: object
      description: >-
        The editable behavior fields. All optional on PATCH (a full-form
        replace);

        on create, missing values fall back to the DB column defaults.
      properties:
        allow_escalation:
          type:
            - boolean
            - 'null'
        allow_patterns:
          type:
            - array
            - 'null'
          items:
            type: string
          description: Replaces the allowlist set wholesale when present.
        category_policy: {}
        court_intake_enabled:
          type:
            - boolean
            - 'null'
          description: >-
            Court-document intake on/off (docs/court-document-intake.md).
            Omitted =

            keep current.
        court_secure_mail_password:
          type:
            - string
            - 'null'
          description: >-
            Secure-mail password for the court portal. WRITE-ONLY: a non-empty
            value

            is vault-sealed and stored; it is never echoed back. Omitted/empty =

            keep the stored password.
        default_reply_lang:
          type:
            - string
            - 'null'
        deliver_to: {}
        enabled:
          type:
            - boolean
            - 'null'
        instructions:
          type:
            - string
            - 'null'
        max_turns_per_day:
          type:
            - integer
            - 'null'
          format: int32
        max_turns_per_sender_day:
          type:
            - integer
            - 'null'
          format: int32
        plane:
          type:
            - string
            - 'null'
        reply_policy:
          type:
            - string
            - 'null'
        sender_policy:
          type:
            - string
            - 'null'
        spam_score_max:
          type:
            - number
            - 'null'
          format: float
    EndpointJson:
      type: object
      required:
        - id
        - localpart
        - kind
        - plane
        - allow_escalation
        - sender_policy
        - reply_policy
        - enabled
        - is_system
        - allow_patterns
        - message_count
        - needs_attention
        - received
        - replied
        - awaiting_review
        - unrouted
        - escalated
        - reply_languages
        - court_intake_enabled
        - court_secure_mail_password_set
        - created_at
        - updated_at
      properties:
        agent_id:
          type:
            - string
            - 'null'
          format: uuid
        allow_escalation:
          type: boolean
        allow_patterns:
          type: array
          items:
            type: string
        awaiting_review:
          type: integer
          format: int64
        category_policy: {}
        court_intake_enabled:
          type: boolean
          description: >-
            Court-document intake (docs/court-document-intake.md) is enabled on
            this

            inbox: an inbound carrying a `securemail.domstol.se` link
            additionally

            downloads the court documents into the library. Off by default.
        court_secure_mail_password_set:
          type: boolean
          description: >-
            A secure-mail password is stored (vault-sealed) for this inbox. The

            password is write-only; this flag is the only thing the API
            discloses.
        created_at:
          type: string
          format: date-time
        default_reply_lang:
          type:
            - string
            - 'null'
        deliver_to: {}
        enabled:
          type: boolean
        escalated:
          type: integer
          format: int64
        id:
          type: string
          format: uuid
        instructions:
          type:
            - string
            - 'null'
        is_system:
          type: boolean
          description: >-
            True for the workspace outbound mailbox (HQ-managed): not deletable,
            not

            a normal custom inbox - the UI renders it as the workspace mailbox.
        kind:
          type: string
        last_occurred_at:
          type:
            - string
            - 'null'
          format: date-time
        localpart:
          type: string
        max_turns_per_day:
          type:
            - integer
            - 'null'
          format: int32
        max_turns_per_sender_day:
          type:
            - integer
            - 'null'
          format: int32
        message_count:
          type: integer
          format: int64
          description: Total mail (in + out) attributed to this endpoint.
        needs_attention:
          type: integer
          format: int64
          description: Items needing a human (handling_state <> 'handled').
        plane:
          type: string
        received:
          type: integer
          format: int64
          description: >-
            Disposition counters (E7.2): inbound received, outbound replies
            sent,

            per-state queues, and threads escalated light -> agent.
        replied:
          type: integer
          format: int64
        reply_languages:
          description: 'Reply-language distribution: `{ "English": 12, "Swedish": 3 }`.'
        reply_policy:
          type: string
        sender_policy:
          type: string
        spam_score_max:
          type:
            - number
            - 'null'
          format: float
        unrouted:
          type: integer
          format: int64
        updated_at:
          type: string
          format: date-time
  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

````