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

# Provision domain

> Provision a single domain to use MailChannels Inbound.



## OpenAPI

````yaml /inbound/api-reference/openapi.yaml post /domains
openapi: 3.0.3
info:
  title: Inbound API
  description: |
    Manage domains for MailChannels Inbound.

    ### Rate Limits
    This API is limited to 100 queries per second, per customer.
    Queries that exceed this rate may be rejected with the
    `503 Service Temporarily Unavailable` HTTP response.
  version: 1.3.0
servers:
  - url: https://api.mailchannels.net/inbound/v1
security:
  - APIKeyHeader: []
tags:
  - name: Domains
  - name: Lists
  - name: Recipients
  - name: Login links
  - name: Reporting
  - name: Account
paths:
  /domains:
    post:
      tags:
        - Domains
      summary: Provision domain
      description: Provision a single domain to use MailChannels Inbound.
      parameters:
        - name: associate-key
          description: >
            If present and set to true, the domain will be associated with the
            api-key that created it.

            This means that this api-key must be used for inbound-api actions
            involving this domain (for

            example adding safe/block list entries, etc).
          in: query
          required: false
          schema:
            type: boolean
        - name: overwrite
          description: >
            If present and set to true, the settings (domain settings,
            downstream addresses, aliases and admins)

            for the domain will be overwritten with the ones in the request if
            the domain already exists, unless

            a section is not included in the request or there is problem
            updating a setting in which case the

            previous settings are carried forward.
          in: query
          required: false
          schema:
            type: boolean
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Domain'
      responses:
        '200':
          description: The domain was already provisioned to use MailChannels Inbound.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Domain'
        '201':
          description: >-
            The domain has been successfully provisioned to use MailChannels
            Inbound.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Domain'
        '400':
          description: >
            Bad Request, returned in the case that an error occurs while
            converting an A-label domain to a U-label domain name.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: >
            A 403 response can be returned in two cases:


            1. The limit on associated domains is reached. Contact
            sales@mailchannels.com to increase your limit.

            2. You are attempting to associate a domain with a subscription that
            is not your own.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: >-
            The domain is already provisioned, and is associated with a
            different customer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    Domain:
      required:
        - domain
        - subscriptionHandle
        - admins
        - aliases
        - downstreamAddresses
      properties:
        domain:
          description: The domain name.
          type: string
          format: hostname
        subscriptionHandle:
          description: >
            The subscription 'handle' that identifies the subscription that this
            domain should be

            provisioned against.  Subscription handles can be retrieved from the
            `/subscriptions`

            endpoint.
          type: string
        settings:
          $ref: '#/components/schemas/DomainSettings'
        admins:
          description: A list of email addresses that are the domain admins for the domain.
          type: array
          items:
            type: string
        downstreamAddresses:
          description: |
            The locations of mail servers to which messages will be delivered
            after filtering.
          type: array
          items:
            $ref: '#/components/schemas/DownstreamAddress'
        aliases:
          description: >
            A list of aliases for the domain. Mail is accepted for these domains
            and

            routed to the downstreamAddresses defined for the domain.
          type: array
          items:
            type: string
    ErrorResponse:
      required:
        - errors
      properties:
        code:
          type: integer
        message:
          type: string
        errors:
          type: array
          items:
            type: string
    DomainSettings:
      properties:
        abusePolicy:
          description: The abuse policy
          type: string
          enum:
            - block
            - flag
            - quarantine
          nullable: true
          minLength: 1
        abusePolicyOverride:
          description: If true, this abuse policy overrides the recipient abuse policy.
          nullable: true
          type: boolean
        spamHeaderName:
          description: The spam header name to use if the abuse policy is set to 'flag'.
          type: string
          nullable: true
          minLength: 1
        spamHeaderValue:
          description: The spam header value to use if the abuse policy is set to 'flag'.
          type: string
          nullable: true
          minLength: 1
    DownstreamAddress:
      type: object
      required:
        - priority
        - weight
        - port
        - target
      properties:
        priority:
          description: >
            The priority of the dowsntream address.  Only addresses with the
            highest priority (the lowest numerical

            value) are selected.
          type: integer
          minimum: 0
        weight:
          description: >
            Downstream addresses are selected in proportion to their weights. 
            For example, if there are two

            downstream addresses, A with weight 40, and B with weight 10, then A
            is selected 80% of the time

            and B is selected 20% of the time.
          type: integer
          minimum: 0
        port:
          description: TCP port on which the downstream mail server is listening.
          type: integer
          minimum: 0
        target:
          description: >-
            The canonical hostname of the host providing the service, ending in
            a dot.
          type: string
          maxLength: 255
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key

````