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

# Create Namespace

> Create a new namespace.



## OpenAPI

````yaml /openapi.documented.yml post /namespaces
openapi: 3.1.0
info:
  title: Nuntly REST API 1.x
  version: 1.0.0-alpha.20
  description: Nuntly REST API definition
  termsOfService: https://nuntly.com/legal/terms-of-service
  contact:
    name: Nuntly Support
    url: https://nuntly.com/docs
    email: support@nuntly.com
servers:
  - description: Nuntly API endpoint
    url: https://api.nuntly.com
security:
  - bearerAuth: []
tags:
  - name: API Keys
    description: >-
      Create and revoke API keys used to authenticate requests to the Nuntly
      API.
  - name: Agents
    description: >-
      Read and write persistent state for an AI agent, optionally scoped to a
      specific inbox or thread.
  - name: Domains
    description: >-
      Add and verify sending and receiving domains. Manage DKIM records, SPF
      configuration, and enable inbound email routing.
  - name: Emails
    description: >-
      Send transactional emails, retrieve sending history, and track delivery
      status per message.
  - name: Inboxes
    description: >-
      Create email inboxes at a specific address on a verified receiving domain.
      Assign inboxes to namespaces or AI agents.
  - name: Messages
    description: >-
      Access received messages, download attachments, and send replies or
      forwards from an inbox.
  - name: Namespaces
    description: >-
      Isolate inboxes by tenant, client, or agent using namespaces. Use an
      external ID to map namespaces to your own data model.
  - name: Organizations
    description: >-
      Manage your organization profile, team members, and account-level
      settings.
  - name: Threads
    description: >-
      Browse email conversations grouped by subject. Mark threads as read or
      spam, and assign them to an agent.
  - name: Webhooks
    description: >-
      Register HTTP endpoints to receive real-time delivery events such as
      bounces, opens, and clicks.
  - name: Webhooks Events
    description: >-
      Inspect webhook event history and replay failed deliveries for debugging
      or recovery.
  - name: Webhooks Hook
    description: >-
      Endpoint your server implements to receive webhook events. Not a Nuntly
      API endpoint - this documents the shape your handler must accept.
externalDocs:
  description: Nuntly API Documentation
  url: https://nuntly.com/docs
paths:
  /namespaces:
    post:
      tags:
        - Namespaces
      summary: Create Namespace
      description: Create a new namespace.
      operationId: create-namespace
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateNamespaceRequest'
      responses:
        '201':
          description: Created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/NamespaceResponse'
                required:
                  - data
                additionalProperties: false
        '500':
          description: An error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-codeSamples:
        - lang: cURL
          source: |-
            curl -X POST 'https://api.nuntly.com/namespaces' \
              -H 'Authorization: Bearer apk_xxx' \
              -H 'Content-Type: application/json' \
              -d '{"name":"<name>"}'
        - lang: JavaScript
          source: |-
            import { Nuntly } from '@nuntly/sdk';

            const client = new Nuntly({
              apiKey: process.env['NUNTLY_API_KEY'],
            });

            const response = await client.namespaces.create({
              name: '<name>',
            });
        - lang: Java
          source: >-
            import com.nuntly.sdk.Nuntly;

            import com.nuntly.sdk.ClientOptions;

            import com.nuntly.sdk.models.*;


            var nuntly = Nuntly.create(ClientOptions.builder()
                .apiKey(System.getenv("NUNTLY_API_KEY"))
                .build());

            var response =
            nuntly.namespaces().create(CreateNamespaceRequest.builder()
                .name("<name>")
                .build());
components:
  schemas:
    CreateNamespaceRequest:
      type: object
      required:
        - name
      properties:
        name:
          description: The display name of the namespace.
          type: string
        externalId:
          description: An optional external identifier for the namespace.
          type: string
    NamespaceResponse:
      type: object
      required:
        - id
        - createdAt
        - name
        - externalId
      properties:
        id:
          description: The id of the namespace
          type: string
          examples:
            - ns_01kabn43yqyxn2bx4ve84mczd3
        createdAt:
          description: Date at which the object was created (ISO 8601 format)
          type: string
          examples:
            - '2026-03-29T12:00:00.000Z'
        updatedAt:
          description: Date at which the object was updated (ISO 8601 format)
          type: string
        name:
          description: The display name of the namespace.
          type: string
        externalId:
          description: The external identifier for the namespace.
          type:
            - string
            - 'null'
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          $ref: '#/components/schemas/Error'
          description: >-
            This object provide you additional information about errors
            encountered while performing the operation
    Error:
      type: object
      required:
        - status
        - code
        - title
      properties:
        status:
          description: >-
            The HTTP status code generated by the origin server for this
            occurrence of the error.
          type: number
        code:
          description: An API specific code representing the type of error.
          type: string
        title:
          description: A short, human-readable summary of the error type.
          type: string
        details:
          description: >-
            A (best effort) human readable explanation specific to this
            occurrence of the error.
          type: object
          additionalProperties: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key (format apk_...)
      description: >-
        Use an API key from https://nuntly.com/api-keys. Required on every
        endpoint.

````