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

# Add a Domain

> Add a sending domain to your account and get the DNS records to publish at your DNS provider. The domain goes through exactly the same checks as **Account Settings → Domains** in the app (format, blocked and ISP domains, subdomain depth, duplicates and your plan's domain limit), and the same DNS records are generated.

The response is the same domain object as **Get a Domain**: `status` is `not_verified` and each record is `pending` (the second DKIM record is `optional`), with a `message` saying what to do at your DNS provider. Open tracking is off for a new domain.

After adding the records at your DNS provider, verify the domain from **Account Settings → Domains**.

**Notes**
- The domain is case-insensitive and a leading `www.` is removed (`WWW.Example.com` is saved as `example.com`).
- Subdomains up to 3 levels below the root are allowed (`news.example.com`, `a.b.c.example.com`).
- Adding a domain can take a few seconds while its DNS is checked.

**Tracking host (`mc.`)**
- For a domain such as `example.com`, the tracking record's host is `mc.example.com`.
- For a subdomain that already exists in your DNS, the host gets a `mc-` prefix instead, e.g. `mc-news.example.com`.
- `mc.example.com` is never treated as `example.com`. If it is not used as a tracking host, it can be added as its own domain: it keeps its full name and gets its own records (tracking host `mc-mc.example.com`).
- If `mc.example.com` is already the tracking host of an added domain (e.g. `example.com` was added first), it cannot be added — the API returns 400 *"This domain is already in use or linked elsewhere"*.



## OpenAPI

````yaml /openapi-v1.json post /domains
openapi: 3.1.0
info:
  title: Mailercloud Marketing API
  version: 1.0.0
  description: >-
    Campaigns, contacts, lists, segments, automations, and webhooks for the
    Mailercloud Marketing Platform.
servers:
  - url: https://cloudapi.mailercloud.com/v1
security:
  - apiKey: []
tags:
  - name: Campaigns
  - name: Contacts
  - name: Lists
  - name: Tags
  - name: Segments
  - name: Custom Properties
  - name: Senders
  - name: Domains
  - name: Templates
  - name: Automations
  - name: Webhooks
  - name: Webforms
  - name: Inbox Tracker
  - name: Account
paths:
  /domains:
    post:
      tags:
        - Domains
      summary: Add a Domain
      description: >-
        Add a sending domain to your account and get the DNS records to publish
        at your DNS provider. The domain goes through exactly the same checks as
        **Account Settings → Domains** in the app (format, blocked and ISP
        domains, subdomain depth, duplicates and your plan's domain limit), and
        the same DNS records are generated.


        The response is the same domain object as **Get a Domain**: `status` is
        `not_verified` and each record is `pending` (the second DKIM record is
        `optional`), with a `message` saying what to do at your DNS provider.
        Open tracking is off for a new domain.


        After adding the records at your DNS provider, verify the domain from
        **Account Settings → Domains**.


        **Notes**

        - The domain is case-insensitive and a leading `www.` is removed
        (`WWW.Example.com` is saved as `example.com`).

        - Subdomains up to 3 levels below the root are allowed
        (`news.example.com`, `a.b.c.example.com`).

        - Adding a domain can take a few seconds while its DNS is checked.


        **Tracking host (`mc.`)**

        - For a domain such as `example.com`, the tracking record's host is
        `mc.example.com`.

        - For a subdomain that already exists in your DNS, the host gets a `mc-`
        prefix instead, e.g. `mc-news.example.com`.

        - `mc.example.com` is never treated as `example.com`. If it is not used
        as a tracking host, it can be added as its own domain: it keeps its full
        name and gets its own records (tracking host `mc-mc.example.com`).

        - If `mc.example.com` is already the tracking host of an added domain
        (e.g. `example.com` was added first), it cannot be added — the API
        returns 400 *"This domain is already in use or linked elsewhere"*.
      operationId: add-a-domain
      parameters:
        - name: Content-Type
          in: header
          required: true
          description: Request body type
          schema:
            type: string
            default: application/json
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - domain
              properties:
                domain:
                  type: string
                  description: >-
                    The domain or subdomain to send from.


                    Minimum: 3

                    Maximum: 100


                    Letters, digits, `-` and `.` only; a label must not start or
                    end with `-`, and the last label must start with a letter.
                  minLength: 3
                  maxLength: 100
            examples:
              Domain:
                value:
                  domain: example.com
              Subdomain:
                value:
                  domain: news.example.com
      responses:
        '201':
          description: Created — the domain object, as returned by Get a Domain
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Domain ID
                  domain:
                    type: string
                    description: Domain name
                  status:
                    type: string
                    enum:
                      - verified
                      - not_verified
                      - failed
                    description: >-
                      Domain status:

                      - `verified` — the domain is authenticated and ready to
                      send.

                      - `not_verified` — the DNS records are not all in place
                      yet (or not checked yet).

                      - `failed` — at least one DNS record was found but is
                      wrong (that record's `status` is `invalid`; see its
                      `error_message` in Get a Domain).
                  open_tracking:
                    type: boolean
                    description: >-
                      Open tracking for Email API / SMTP sends from this domain.
                      No effect on marketing campaigns. Off for a newly added
                      domain.
                  records:
                    type: array
                    description: DNS records to publish at your DNS provider
                    items:
                      type: object
                      properties:
                        type:
                          type: string
                          enum:
                            - CNAME
                            - TXT
                            - CAA
                          description: Record type
                        host:
                          type: string
                          description: Host / name of the record
                        value:
                          type: string
                          description: Value to enter at your DNS provider
                        status:
                          type: string
                          enum:
                            - pending
                            - verified
                            - invalid
                            - optional
                          description: >-
                            - `pending` — not added yet, or not checked yet

                            - `verified` — found and correct

                            - `invalid` — found but wrong (see `error_message`)

                            - `optional` — the second DKIM record (`dkim2`), not
                            added yet; it is only needed for automatic DKIM key
                            rotation
                        purpose:
                          type: string
                          enum:
                            - tracking
                            - dkim
                            - dkim2
                            - image
                            - dmarc
                            - spf
                            - caa
                          description: >-
                            What the record is for:

                            - `tracking` — Return-Path & tracking host
                            (`mc.example.com`)

                            - `dkim` — DKIM signature

                            - `dkim2` — optional second DKIM record (key
                            rotation)

                            - `image` — image hosting

                            - `dmarc` — DMARC policy

                            - `spf` — SPF

                            - `caa` — lets us issue the SSL certificate for your
                            tracking and image hosts (only when your existing
                            CAA record would block it)
                        message:
                          type: string
                          description: >-
                            What to do at your DNS provider. Left out when the
                            record is verified.

                            - *Add the record to your domain provider*

                            - *Update the record in your domain provider* — an
                            existing record must be changed (DMARC)

                            - *Edit and update the record in your domain
                            provider* — the record is invalid
                        error_message:
                          type: string
                          description: >-
                            Why the record is invalid. Only present when
                            `status` is `invalid`.
                  created_at:
                    type: string
                    description: >-
                      When the domain was added, in your account timezone
                      (`YYYY-MM-DD HH:MM:SS`)
              examples:
                Example-1:
                  value:
                    id: zjAKXb
                    domain: example.com
                    status: not_verified
                    open_tracking: false
                    records:
                      - type: CNAME
                        host: mc.example.com
                        value: mc3035n.mlrcloud.com
                        status: pending
                        purpose: tracking
                        message: Add the record to your domain provider
                      - type: CNAME
                        host: k1._domainkey.example.com
                        value: dkim.mlrcloud.com
                        status: pending
                        purpose: dkim
                        message: Add the record to your domain provider
                      - type: CNAME
                        host: k2._domainkey.example.com
                        value: dkim2.mlrcloud.com
                        status: optional
                        purpose: dkim2
                        message: Add the record to your domain provider
                      - type: CNAME
                        host: img3035n.example.com
                        value: img3035n.mlrcloud.com
                        status: pending
                        purpose: image
                        message: Add the record to your domain provider
                      - type: TXT
                        host: _dmarc.example.com
                        value: >-
                          v=DMARC1; p=reject; sp=none; adkim=s; aspf=s;
                          rua=mailto:dmarc@mlrcloud.com;
                          ruf=mailto:dmarc@mlrcloud.com;
                        status: pending
                        purpose: dmarc
                        message: Update the record in your domain provider
                    created_at: '2026-10-15 18:32:12'
        '400':
          description: >-
            Bad Request — invalid input or the domain was refused (same messages
            as the app)
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        field:
                          type: string
                        message:
                          type: string
              examples:
                Invalid input:
                  value:
                    errors:
                      - field: ''
                        message: Invalid input
                Invalid domain:
                  value:
                    errors:
                      - field: domain
                        message: Invalid domain
                Already exists:
                  value:
                    errors:
                      - field: domain
                        message: Your domain example.com already exists
                Already authenticated:
                  value:
                    errors:
                      - field: domain
                        message: Your domain example.com already authenticated
                ISP or disposable domain:
                  value:
                    errors:
                      - field: domain
                        message: >-
                          Sorry! We block some major ISP domains due to their
                          DMARC policy
                Blocked domain:
                  value:
                    errors:
                      - field: domain
                        message: >-
                          Our anti-spam monitoring system blocked your domain.
                          To be de-listed, contact us at
                          support@mailercloud.com.
                Contains mailercloud:
                  value:
                    errors:
                      - field: domain
                        message: Domain cannot contain mailercloud
                Domain hierarchy:
                  value:
                    errors:
                      - field: domain
                        message: >-
                          Domain addition was unsuccessful due to domain
                          hierarchy
                In use by another account:
                  value:
                    errors:
                      - field: domain
                        message: >-
                          The domain is already in use with another account.
                          Please contact our support team for further
                          assistance.
                Linked elsewhere:
                  value:
                    errors:
                      - field: domain
                        message: >-
                          This domain is already in use or linked elsewhere.
                          Please enter a different domain to continue.
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        field:
                          type: string
                        message:
                          type: string
              examples:
                Example-1:
                  value:
                    errors:
                      - field: ''
                        message: Authorization failed
        '403':
          description: Forbidden — your plan's domain limit is reached
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        field:
                          type: string
                        message:
                          type: string
              examples:
                Free plan limit:
                  value:
                    errors:
                      - field: domain
                        message: >-
                          Free plan users can add only 1 domain. To add more
                          domains, please upgrade your plan.
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              examples:
                Example-1:
                  value:
                    message: Too Many Requests
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              examples:
                Example-1:
                  value:
                    message: >-
                      Sorry, we are experiencing some technical difficulties.
                      Please try after some time.
components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        Your Mailercloud API key (plain text, no Bearer prefix). Create keys in
        Settings → API.

````

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