> ## 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.

# Create inbox

> Create a new inbox for an agent. The domain is auto-resolved if not provided.

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

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

  const inbox = await commune.inboxes.create({
    localPart: 'support',
    name: 'Support Agent',
    domainId: 'domain_xyz789',
  });

  console.log(inbox.data.address);  // support@mycompany.com
  console.log(inbox.data.id);       // uuid
  ```

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

  client = CommuneClient()

  inbox = client.inboxes.create(
      local_part="support",
      name="Support Agent",
      domain_id="domain_xyz789",
  )

  print(inbox.data.address)  # support@mycompany.com
  ```

  ```bash MCP theme={null}
  create_inbox(
    local_part="support",
    name="Support Agent"
  )
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.commune.email/v1/inboxes \
    -H "Authorization: Bearer comm_..." \
    -H "Content-Type: application/json" \
    -d '{
      "local_part": "support",
      "name": "Support Agent",
      "domain_id": "domain_xyz789"
    }'
  ```

  ```bash CLI theme={null}
  commune inboxes create --local-part "support" --name "Support Agent" --domain-id "domain_xyz789"
  ```
</RequestExample>

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "data": {
      "id": "3d4f5a6b-7c8d-9e0f-a1b2-c3d4e5f6a7b8",
      "localPart": "support",
      "address": "support@mycompany.com",
      "displayName": "Support Agent",
      "agent": {
        "name": "Support Agent"
      },
      "status": "active",
      "createdAt": "2026-02-25T10:00:00.000Z",
      "domain_id": "domain_xyz789",
      "domain_name": "mycompany.com"
    }
  }
  ```

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

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

  ```json 404 Not Found theme={null}
  {
    "error": "Domain not found"
  }
  ```
</ResponseExample>

## Body

<ParamField body="local_part" type="string" required>
  The local part of the email address (the part before `@`). For example, `"support"` creates `support@yourdomain.com`.

  Accepts either `local_part` or `localPart`.
</ParamField>

<ParamField body="domain_id" type="string">
  ID of the domain to create the inbox on. If not provided, Commune auto-resolves the domain for your organization — using your first custom domain, or falling back to the shared Commune domain.

  Accepts either `domain_id` or `domainId`.
</ParamField>

<ParamField body="name" type="string">
  Display name for the inbox and the associated agent. Shown as the `From` display name when sending email from this inbox (e.g. `"Support Agent" <support@mycompany.com>`).

  Also accepted as `display_name` or `displayName`.
</ParamField>

<ParamField body="webhook" type="object">
  Webhook configuration for inbound messages to this inbox.

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

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

<ParamField body="status" type="string">
  Initial inbox status. Defaults to `"active"`.
</ParamField>

## Response

<ResponseField name="data" type="object">
  <Expandable title="properties" defaultOpen>
    <ResponseField name="id" type="string">
      Unique inbox identifier (UUID).
    </ResponseField>

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

    <ResponseField name="address" type="string">
      Full email address of the inbox (e.g. `support@mycompany.com`).
    </ResponseField>

    <ResponseField name="displayName" type="string">
      Display name shown in the `From` header when sending.
    </ResponseField>

    <ResponseField name="agent" type="object">
      <Expandable title="properties">
        <ResponseField name="name" type="string">Agent name.</ResponseField>
        <ResponseField name="id" type="string">Agent ID, if linked to an agent identity.</ResponseField>
      </Expandable>
    </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 webhook verification.</ResponseField>
      </Expandable>
    </ResponseField>

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

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

    <ResponseField name="domain_id" type="string">
      ID of the domain this inbox belongs to.
    </ResponseField>

    <ResponseField name="domain_name" type="string">
      Domain name (e.g. `mycompany.com`). Only present when the domain is auto-resolved.
    </ResponseField>
  </Expandable>
</ResponseField>


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