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

# Create domain

> **Endpoint:** `v1/domains`

Create a new domain for sending emails. The domain name must be in a valid format (e.g., example.com, env.example.com).




## OpenAPI

````yaml api-reference/openapi.yml post /domains
openapi: 3.1.0
info:
  title: Send Email API
  description: >
    Send transactional emails through MailDiver.


    ### Base URL

    All API endpoints are prefixed with `api.` subdomain:

    ```

    https://api.maildiver.com

    ```


    For the self-hosted version, if your domain is `example.com`:

    ```

    https://api.example.com

    ```


    ### Endpoint

    ```

    v1/emails

    ```


    ### Authentication

    All API requests require authentication using your API key in the
    Authorization header:

    ```

    Authorization: Bearer your-api-key

    ```
  version: 1.0.0
  license:
    name: MIT
servers:
  - url: https://api.maildiver.com/v1
    description: Production server
    variables:
      domain:
        default: yourdomain.com
        description: Your domain (without the api. prefix)
security:
  - bearerAuth: []
paths:
  /domains:
    post:
      tags:
        - Domain
      summary: Create domain
      description: >
        **Endpoint:** `v1/domains`


        Create a new domain for sending emails. The domain name must be in a
        valid format (e.g., example.com, env.example.com).
      operationId: createDomain
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                  description: |
                    Domain name. Must be:
                    - At least 4 characters long
                    - Maximum 253 characters
                    - In a valid format (e.g., example.com, env.example.com)
                  minLength: 4
                  maxLength: 253
                  example: hello.com
            examples:
              valid:
                summary: Valid domain name
                value:
                  name: hello.com
              invalid:
                summary: Invalid domain name
                value:
                  name: my-domain
      responses:
        '200':
          description: Domain successfully created
          content:
            application/json:
              examples:
                success:
                  summary: Success response
                  value:
                    id: 0195ce56-005e-71ee-add6-30d090ced7ed
                    name: hello.com
                    status: NOT_STARTED
                    dns_records:
                      - type: TXT
                        name: dkim._domainkey
                        value: >-
                          p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQD7mOzhK4x4kXwCdTbF1E4hDqj20f2/HVuFnnYhASOOuHo9Go6AHE14E+sJRW5yOuEFUJLssYKImYCBDtJ2y5SJcR1DxDKyYYiaixCwTqmfB1osXxqESb4BgFC67trrDEzEgQn2K+Hm0Cmzrohfuj4z+ln9wO+wkkt/k02qE6QawQIDAQAB
                        required: true
                        for: DKIM
                      - type: MX
                        name: send
                        value: feedback-smtp.eu-central-1.amazonses.com
                        priority: 10
                        required: true
                        for: MAIL FROM domain
                      - type: TXT
                        name: send
                        value: '"v=spf1 include:amazonses.com ~all"'
                        required: true
                        for: MAIL FROM domain
                      - type: TXT
                        name: _dmarc
                        value: v=DMARC1; p=none;
                        required: false
                        for: DMARC (highly recommended)
        '400':
          description: Bad request
          content:
            application/json:
              examples:
                invalidFormat:
                  summary: Invalid domain name format
                  value:
                    message: >-
                      Invalid domain name format: my-domain. Valid formats:
                      example.com, env.example.com, etc.
                tooShort:
                  summary: Domain name too short
                  value:
                    message: Domain name must be at least 4 characters long
                tooLong:
                  summary: Domain name too long
                  value:
                    message: Domain name cannot exceed 253 characters
        '403':
          description: Forbidden (API key is missing or invalid)
          content:
            application/json:
              examples:
                invalidKey:
                  summary: Invalid API key error
                  value:
                    message: Invalid API key
                    code: invalid_api_key
                invalidHeader:
                  summary: Invalid authorization header error
                  value:
                    message: Invalid authorization header
                    code: invalid_authorization_header
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key with format "Bearer {your-api-key}"

````