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

# Create a mailbox

> Creates a mailbox on the domain and returns it with the generated password in plaintext. That password is readable in this response alone; it is stored hashed and can only be replaced, never retrieved. The mailbox is created in the provisioning status and becomes usable once the provisioning consumer has applied the change downstream. Requires the `mailboxes:write` scope.



## OpenAPI

````yaml /api-reference/openapi.json post /api/v1/user/mailbox-domains/{mailboxDomainId}/mailboxes
openapi: 3.0.0
info:
  title: Brudcast API
  version: 1.0.0
servers:
  - url: https://core-service.prod.brudcast.com
    description: Production
security: []
tags:
  - name: Analytics
    x-displayName: Analytics
  - name: Campaigns
    x-displayName: Campaigns
  - name: Contacts
    x-displayName: Contacts
  - name: Mailboxes
    x-displayName: Mailboxes
  - name: Messages
    x-displayName: Messages
  - name: Sender Identities
    x-displayName: Sender Identities
  - name: Sending Domains
    x-displayName: Sending Domains
  - name: Templates
    x-displayName: Templates
  - name: Webhooks
    x-displayName: Webhooks
paths:
  /api/v1/user/mailbox-domains/{mailboxDomainId}/mailboxes:
    post:
      tags:
        - Mailboxes
      summary: Create a mailbox
      description: >-
        Creates a mailbox on the domain and returns it with the generated
        password in plaintext. That password is readable in this response alone;
        it is stored hashed and can only be replaced, never retrieved. The
        mailbox is created in the provisioning status and becomes usable once
        the provisioning consumer has applied the change downstream. Requires
        the `mailboxes:write` scope.
      parameters:
        - in: header
          name: X-Organization-Id
          required: false
          description: >-
            Required when authenticating with an access token. Optional with an
            API key, whose own organization binding is authoritative; a value
            contradicting it is refused with 403.
          schema:
            type: string
            format: uuid
        - in: path
          name: mailboxDomainId
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                localPart:
                  type: string
                  minLength: 1
                  maxLength: 64
                  pattern: ^[a-z0-9]+(?:[._-][a-z0-9]+)*$
                displayName:
                  type: string
                  minLength: 1
                  maxLength: 255
                quotaBytes:
                  type: integer
                  minimum: 1073741824
                  maximum: 107374182400
              required:
                - localPart
              additionalProperties: false
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailboxWithPasswordResponse'
        '400':
          description: >-
            The organization is at its mailbox cap, the local part is reserved,
            or the address is already taken by a mailbox or an alias
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The credential is missing, malformed, revoked or expired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: >-
            The key lacks the scope the endpoint requires, or the organization
            does not match the credential
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: No such mailbox domain in the organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: The payload or query string failed validation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
        '429':
          description: >-
            Rate limit exceeded; retry after the number of seconds in
            `retryAfter`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitErrorResponse'
      security:
        - apiKey: []
        - apiKeyBearer: []
components:
  schemas:
    MailboxWithPasswordResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
        data:
          $ref: '#/components/schemas/MailboxWithPassword'
      required:
        - success
        - message
        - data
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        message:
          type: string
          example: Resource not found
        code:
          type: string
          enum:
            - E_VALIDATION_ERROR
            - E_UNAUTHORIZED_ACCESS
            - E_UNAUTHORIZED
            - E_FORBIDDEN
            - E_INSUFFICIENT_SCOPE
            - E_ROW_NOT_FOUND
            - E_TOO_MANY_REQUESTS
            - E_BUSINESS_RULE_VIOLATION
            - E_CAMPAIGN_NOT_SENDABLE
            - INSUFFICIENT_CREDITS
            - SUBSCRIPTION_REQUIRED
          example: E_ROW_NOT_FOUND
      required:
        - success
        - message
        - code
    ValidationErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        message:
          type: string
          example: The payload is invalid
        code:
          type: string
          enum:
            - E_VALIDATION_ERROR
            - E_UNAUTHORIZED_ACCESS
            - E_UNAUTHORIZED
            - E_FORBIDDEN
            - E_INSUFFICIENT_SCOPE
            - E_ROW_NOT_FOUND
            - E_TOO_MANY_REQUESTS
            - E_BUSINESS_RULE_VIOLATION
            - E_CAMPAIGN_NOT_SENDABLE
            - INSUFFICIENT_CREDITS
            - SUBSCRIPTION_REQUIRED
          example: E_VALIDATION_ERROR
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ValidationErrorItem'
      required:
        - success
        - message
        - code
        - errors
    RateLimitErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        message:
          type: string
          example: Too many requests
        code:
          type: string
          enum:
            - E_VALIDATION_ERROR
            - E_UNAUTHORIZED_ACCESS
            - E_UNAUTHORIZED
            - E_FORBIDDEN
            - E_INSUFFICIENT_SCOPE
            - E_ROW_NOT_FOUND
            - E_TOO_MANY_REQUESTS
            - E_BUSINESS_RULE_VIOLATION
            - E_CAMPAIGN_NOT_SENDABLE
            - INSUFFICIENT_CREDITS
            - SUBSCRIPTION_REQUIRED
          example: E_TOO_MANY_REQUESTS
        retryAfter:
          type: number
          example: 60
      required:
        - success
        - message
        - code
        - retryAfter
    MailboxWithPassword:
      type: object
      properties:
        id:
          type: string
          format: uuid
        mailboxDomainId:
          type: string
          format: uuid
        organizationId:
          type: string
          format: uuid
        address:
          type: string
          format: email
          example: jane@example.com
        displayName:
          type: string
          nullable: true
          example: Jane Doe
        status:
          type: string
          enum:
            - provisioning
            - active
            - provisioning_failed
            - suspended
          description: >-
            Reflects the control plane, which flips ahead of the mail server. A
            mailbox reads as provisioning until the provisioning consumer has
            applied the change
        quotaBytes:
          type: number
          example: 1073741824
        usedBytes:
          type: number
          description: >-
            Storage the mailbox currently occupies, as last reported by the mail
            server
        deletedAt:
          type: string
          format: date-time
          nullable: true
          description: >-
            Always null on a returned mailbox; removed mailboxes are soft
            deleted and filtered out of every read
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        aliases:
          type: array
          items:
            $ref: '#/components/schemas/MailboxAlias'
          description: Empty on a mailbox that was just created
        mailboxDomain:
          $ref: '#/components/schemas/MailboxDomain'
          description: >-
            Present only in the organization-wide mailbox list, which spans
            several domains
        password:
          type: string
          description: >-
            The plaintext password, returned by this response alone. It is
            stored hashed and cannot be read again; a caller that loses it must
            reset the password
      required:
        - id
        - mailboxDomainId
        - organizationId
        - address
        - displayName
        - status
        - quotaBytes
        - usedBytes
        - deletedAt
        - createdAt
        - updatedAt
        - aliases
        - password
    ValidationErrorItem:
      type: object
      properties:
        field:
          type: string
          example: emailAddress
        rule:
          type: string
          example: email
        message:
          type: string
          example: The emailAddress field must be a valid email address
      required:
        - field
        - rule
        - message
    MailboxAlias:
      type: object
      properties:
        id:
          type: string
          format: uuid
        mailboxId:
          type: string
          format: uuid
        address:
          type: string
          format: email
          example: sales@example.com
          description: Always on the mailbox's own domain
        deletedAt:
          type: string
          format: date-time
          nullable: true
          description: >-
            Always null on a returned alias; removed aliases are soft deleted
            and filtered out of every read
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
        - id
        - mailboxId
        - address
        - deletedAt
        - createdAt
        - updatedAt
    MailboxDomain:
      type: object
      properties:
        id:
          type: string
          format: uuid
        organizationId:
          type: string
          format: uuid
        sendingDomainId:
          type: string
          format: uuid
          nullable: true
          description: >-
            The outbound sending domain of the same name, when the organization
            also sends from it. Null on an inbound-only domain
        name:
          type: string
          example: example.com
        status:
          type: string
          enum:
            - pending
            - verifying
            - active
            - verification_failed
        dkimSelector:
          type: string
          nullable: true
          description: Null until the mailbox service reports the DKIM keypair it minted
        dkimPublicKey:
          type: string
          nullable: true
          description: Null until the mailbox service reports the DKIM keypair it minted
        lastVerificationAttempt:
          type: string
          format: date-time
          nullable: true
        verifiedAt:
          type: string
          format: date-time
          nullable: true
        deletedAt:
          type: string
          format: date-time
          nullable: true
          description: >-
            Always null on a returned domain; removed domains are soft deleted
            and filtered out of every read
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        dnsRecords:
          type: array
          items:
            $ref: '#/components/schemas/MailboxDomainDnsRecord'
          description: Present when the domain is fetched individually
      required:
        - id
        - organizationId
        - sendingDomainId
        - name
        - status
        - dkimSelector
        - dkimPublicKey
        - lastVerificationAttempt
        - verifiedAt
        - deletedAt
        - createdAt
        - updatedAt
    MailboxDomainDnsRecord:
      type: object
      properties:
        id:
          type: string
          format: uuid
        mailboxDomainId:
          type: string
          format: uuid
        type:
          type: string
          enum:
            - TXT
            - CNAME
            - MX
            - SRV
        name:
          type: string
          example: mail.example.com
        value:
          type: string
          example: mx.brudcast.com
        purpose:
          type: string
          enum:
            - verification
            - dkim
            - spf
            - dmarc
            - tracking
            - mx
            - autoconfig
            - autodiscover
            - srv
        description:
          type: string
          nullable: true
        priority:
          type: number
          nullable: true
          example: 10
          description: Set on MX and SRV records only
        weight:
          type: number
          nullable: true
          description: Set on SRV records only
        port:
          type: number
          nullable: true
          description: Set on SRV records only
        ttl:
          type: number
          example: 3600
        isVerified:
          type: boolean
          description: True once `verifiedAt` carries a timestamp
        scope:
          type: string
          enum:
            - sending
            - mailbox
            - shared
          description: >-
            Which product the record serves, so a domain used for both mailboxes
            and sending shows one merged set rather than two conflicting ones
        verifiedAt:
          type: string
          format: date-time
          nullable: true
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
        - id
        - mailboxDomainId
        - type
        - name
        - value
        - purpose
        - description
        - priority
        - weight
        - port
        - ttl
        - isVerified
        - scope
        - verifiedAt
        - createdAt
        - updatedAt
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        An organization API key, prefixed `bk_live_`. Takes precedence over
        `Authorization` when both are sent. The key is bound to one
        organization, and the scopes it was issued with are enforced per
        endpoint.
    apiKeyBearer:
      type: http
      scheme: bearer
      bearerFormat: bk_live_...
      description: >-
        The same organization API key sent as `Authorization: Bearer
        bk_live_...`. Accepted only when the value begins with `bk_` and no
        `X-API-Key` header is present.

````