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

# Update inbox

> Update an inbox's settings, such as the sender display name shown in the From header.



## OpenAPI

````yaml https://api.openmail.sh/openapi.json patch /v1/inboxes/{id}
openapi: 3.0.3
info:
  title: OpenMail API
  description: >-
    Email infrastructure API for AI agents. Create inboxes, send and receive
    email, and get real-time notifications via webhooks.
  version: 1.0.0
  license:
    name: Proprietary
servers:
  - url: https://api.openmail.sh
security:
  - bearerAuth: []
tags:
  - name: pods
    description: Isolated sub-accounts for your end users or tenants
  - name: inboxes
    description: Email inboxes and their webhook configuration
  - name: domains
    description: >-
      Custom domains: add your own sending/receiving domain, publish DNS, and
      verify it
  - name: owned-domains
    description: >-
      Domains your organisation controls but does not send from. Prove ownership
      with one TXT record and mail to their addresses stops counting toward the
      cold outreach limits.
  - name: messages
    description: Sending and listing messages
  - name: drafts
    description: Create, view, edit and send saved email drafts
  - name: threads
    description: Conversation threads and read status
  - name: attachments
    description: Downloading and extracting text from attachments
  - name: policy
    description: >-
      Correspondent policy — provider-enforced allow/block rules and allowlist
      mode, scoped per account, pod, or inbox. Account-wide key only.
  - name: limits
    description: >-
      Sending limits: today's cold outreach caps on new recipients, per account,
      inbox, and domain, and what raises them
  - name: webhooks
    description: >-
      Webhook endpoints: where events are sent, how each request is
      authenticated, and the delivery log. Account-wide key only.
  - name: feedback
    description: Reporting bugs, friction, and feature requests to the OpenMail team
paths:
  /v1/inboxes/{id}:
    patch:
      tags:
        - inboxes
      summary: Update inbox
      description: >-
        Update an inbox's settings, such as the sender display name shown in the
        From header.
      operationId: updateInbox
      parameters:
        - schema:
            type: string
          in: path
          name: id
          required: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                displayName:
                  type: string
                  maxLength: 200
                  description: >-
                    Sender display name. Unicode and punctuation are supported.
                    No control characters, line breaks, tabs, or surrounding
                    whitespace. Set null or an empty string to clear.
                  nullable: true
                webhookUrl:
                  type: string
                  minLength: 0
                  description: >-
                    URL to receive signed webhook events for this inbox. Set
                    null to clear and revert to the account-level webhook. A
                    signing secret is generated the first time a webhook URL is
                    set on this inbox and returned once in the response body.
                  nullable: true
                forwardTo:
                  type: string
                  description: >-
                    Email address that receives a copy of inbound messages, e.g.
                    your own Gmail. Members of your organisation are confirmed
                    at once; any other address is emailed a confirmation link
                    and `forwardStatus` stays `pending` until they click it.
                    Re-sending the same pending address re-issues the link.
                    Setting a new address also re-enables forwarding that was
                    paused for bouncing. Set null to stop forwarding.
                  nullable: true
                forwardWhen:
                  type: string
                  enum:
                    - always
                    - needs_human
                    - webhook_failed
                    - null
                  description: >-
                    When to forward. `always` (default); `needs_human` only mail
                    the agent should not auto-handle (`autoReplyable` false);
                    `webhook_failed` only once webhook delivery has exhausted
                    its retries or there was no webhook or WebSocket to deliver
                    to.
                  nullable: true
      responses:
        '200':
          description: Inbox updated
          content:
            application/json:
              schema:
                description: Inbox updated
                allOf:
                  - $ref: '#/components/schemas/Inbox'
        '400':
          description: Invalid sender display name (`invalid_display_name`)
          content:
            application/json:
              schema:
                description: Invalid sender display name (`invalid_display_name`)
                allOf:
                  - $ref: '#/components/schemas/Error'
        '403':
          description: >-
            The authenticating key is inbox-scoped (read + send only) and cannot
            modify the inbox
          content:
            application/json:
              schema:
                description: >-
                  The authenticating key is inbox-scoped (read + send only) and
                  cannot modify the inbox
                allOf:
                  - $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                description: Not found
                allOf:
                  - $ref: '#/components/schemas/Error'
        '422':
          description: >-
            `webhookUrl` failed validation (`invalid_webhook_url`), or
            forwarding settings were rejected (`invalid_forward_to`,
            `forward_to_is_openmail_address`, `forward_verification_cooldown`,
            `invalid_forward_when`, `forward_when_requires_forward_to`)
          content:
            application/json:
              schema:
                description: >-
                  `webhookUrl` failed validation (`invalid_webhook_url`), or
                  forwarding settings were rejected (`invalid_forward_to`,
                  `forward_to_is_openmail_address`,
                  `forward_verification_cooldown`, `invalid_forward_when`,
                  `forward_when_requires_forward_to`)
                allOf:
                  - $ref: '#/components/schemas/Error'
        '429':
          description: >-
            10 forwarding confirmation emails already sent this hour
            (`forward_verification_limit`)
          content:
            application/json:
              schema:
                description: >-
                  10 forwarding confirmation emails already sent this hour
                  (`forward_verification_limit`)
                allOf:
                  - $ref: '#/components/schemas/Error'
components:
  schemas:
    Inbox:
      type: object
      additionalProperties: true
      properties:
        id:
          type: string
          description: OpenMail inbox ID
        podId:
          type: string
          description: >-
            ID of the pod this inbox belongs to. Inboxes created without an
            explicit pod land in your account's default pod.
        address:
          type: string
          format: email
          description: Full email address
        aliases:
          type: array
          description: >-
            Previous receiving addresses and their expiry. Outbound mail uses
            address.
          items:
            type: object
            required:
              - address
              - receiveUntil
              - active
            properties:
              address:
                type: string
                format: email
              receiveUntil:
                type: string
                format: date-time
                nullable: true
              active:
                type: boolean
        displayName:
          type: string
          description: Sender display name
          nullable: true
        webhookUrl:
          type: string
          description: >-
            URL that receives signed webhook events for this inbox, if set.
            Overrides the account-level webhook for this inbox only.
          nullable: true
        webhookSecret:
          type: string
          description: >-
            Signing secret for this inbox's webhook. Only present in the
            response when the secret is generated or rotated (on create, on
            first setting a webhook URL, or via the rotate-secret endpoint) — it
            is never returned afterward.
          nullable: true
        forwardTo:
          type: string
          description: Address that receives copies of this inbox's inbound mail, if set.
          nullable: true
        forwardWhen:
          type: string
          enum:
            - always
            - needs_human
            - webhook_failed
            - null
          description: Which inbound mail is forwarded. Null when forwarding is not set.
          nullable: true
        forwardStatus:
          type: string
          enum:
            - pending
            - active
            - disabled
            - null
          description: >-
            `pending` until the address confirms via the emailed link (members
            of your organisation are confirmed at once); `active` once copies
            are flowing; `disabled` when forwarding paused itself after the
            address hard-bounced repeatedly or complained — set `forwardTo`
            again to resume. Null when forwarding is not set.
          nullable: true
        createdAt:
          type: string
          format: date-time
    Error:
      type: object
      additionalProperties: true
      properties:
        error:
          type: string
        message:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key

````

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