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

# Update inbox

> Update an inbox's local part, webhook configuration, or status.

<RequestExample>
  ```typescript TypeScript theme={null}
  import { CommuneClient } from 'commune-ai';

  const commune = new CommuneClient({ apiKey: process.env.COMMUNE_API_KEY });

  const updated = await commune.inboxes.setWebhook(
    'domain_xyz789',
    '3d4f5a6b-7c8d-9e0f-a1b2-c3d4e5f6a7b8',
    {
      endpoint: 'https://myapp.com/webhooks/email',
      events: ['inbound'],
    }
  );

  console.log(updated.data.webhook.endpoint);
  ```

  ```python Python theme={null}
  from commune import CommuneClient

  client = CommuneClient()

  updated = client.inboxes.set_webhook(
      domain_id="domain_xyz789",
      inbox_id="3d4f5a6b-7c8d-9e0f-a1b2-c3d4e5f6a7b8",
      endpoint="https://myapp.com/webhooks/email",
      events=["inbound"],
  )

  print(updated.data.webhook.endpoint)
  ```

  ```bash MCP theme={null}
  update_inbox(
    domain_id="domain_xyz789",
    inbox_id="3d4f5a6b-7c8d-9e0f-a1b2-c3d4e5f6a7b8",
    webhook_endpoint="https://myapp.com/webhooks/email",
    webhook_events=["inbound"]
  )
  ```

  ```bash cURL theme={null}
  curl -X PUT "https://api.commune.email/v1/domains/domain_xyz789/inboxes/3d4f5a6b-7c8d-9e0f-a1b2-c3d4e5f6a7b8" \
    -H "Authorization: Bearer comm_..." \
    -H "Content-Type: application/json" \
    -d '{
      "webhook": {
        "endpoint": "https://myapp.com/webhooks/email",
        "events": ["inbound"]
      }
    }'
  ```

  ```bash CLI theme={null}
  commune inboxes update 3d4f5a6b-7c8d-9e0f-a1b2-c3d4e5f6a7b8 \
    --webhook-endpoint "https://myapp.com/webhooks/email" \
    --webhook-events inbound
  ```
</RequestExample>

<ResponseExample>
  ```json 200 Success theme={null}
  {
    "data": {
      "id": "3d4f5a6b-7c8d-9e0f-a1b2-c3d4e5f6a7b8",
      "localPart": "support",
      "address": "support@mycompany.com",
      "displayName": "Support Agent",
      "webhook": {
        "endpoint": "https://myapp.com/webhooks/email",
        "events": ["inbound"],
        "secret": "whsec_abc123..."
      },
      "status": "active",
      "createdAt": "2026-02-25T10:00:00.000Z"
    }
  }
  ```

  ```json 400 Bad Request theme={null}
  {
    "error": "Missing required field: local_part"
  }
  ```

  ```json 404 Not Found theme={null}
  {
    "error": "Inbox not found"
  }
  ```

  ```json 401 Unauthorized theme={null}
  {
    "error": "unauthorized",
    "message": "Invalid or missing API key"
  }
  ```
</ResponseExample>

## Path Parameters

<ParamField path="domainId" type="string" required>
  The domain ID the inbox belongs to.
</ParamField>

<ParamField path="inboxId" type="string" required>
  The inbox ID (UUID) to update.
</ParamField>

## Body

All body fields are optional. Only provided fields are updated; others retain their existing values.

<ParamField body="local_part" type="string">
  New local part for the inbox address. Accepts either `local_part` or `localPart`.
</ParamField>

<ParamField body="webhook" type="object">
  Updated webhook configuration. Replaces the entire existing webhook config.

  <Expandable title="properties">
    <ParamField body="endpoint" type="string">
      HTTPS URL to receive webhook events.
    </ParamField>

    <ParamField body="events" type="string[]">
      Event types to subscribe to. Example: `["inbound"]`.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="status" type="string">
  New inbox status. Example values: `"active"`, `"inactive"`.
</ParamField>

## Response

<ResponseField name="data" type="object">
  The updated inbox object. Same shape as [Get inbox](/api-reference/inboxes/get).

  <Expandable title="properties" defaultOpen>
    <ResponseField name="id" type="string">
      Inbox ID (unchanged).
    </ResponseField>

    <ResponseField name="localPart" type="string">
      Updated local part of the inbox address.
    </ResponseField>

    <ResponseField name="address" type="string">
      Full email address of the inbox.
    </ResponseField>

    <ResponseField name="displayName" type="string">
      Display name shown in outbound `From` headers.
    </ResponseField>

    <ResponseField name="webhook" type="object">
      <Expandable title="properties">
        <ResponseField name="endpoint" type="string">Webhook endpoint URL.</ResponseField>
        <ResponseField name="events" type="string[]">Subscribed event types.</ResponseField>
        <ResponseField name="secret" type="string">HMAC signing secret for payload verification.</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="status" type="string">
      Current inbox status.
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO 8601 creation timestamp.
    </ResponseField>
  </Expandable>
</ResponseField>


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