> ## 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. # Update a Domain > Change one or more DNS record host labels and/or open tracking in one call — the same changes as the edit (pencil) icon and the open-tracking toggle in **Account Settings → Domains**. Send at least one field. **All fields are checked first; if any is invalid nothing is changed.** Each renamed record gets its new host and `status: pending`: add the new record at your DNS provider and **Verify a Domain** again. The response is the same domain object as **Get a Domain**. **Notes** - `tracking_prefix` is the tracking / Return-Path host (`mc` in `mc.example.com`). It cannot be changed for a subdomain. - For a subdomain, the image record's host is on the root domain (e.g. `img2.example.com` for `news.example.com`). - The DKIM and second DKIM selectors must be different. ## OpenAPI ````yaml /openapi-v1.json put /domains/{id} 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/{id}: put: tags: - Domains summary: Update a Domain description: >- Change one or more DNS record host labels and/or open tracking in one call — the same changes as the edit (pencil) icon and the open-tracking toggle in **Account Settings → Domains**. Send at least one field. **All fields are checked first; if any is invalid nothing is changed.** Each renamed record gets its new host and `status: pending`: add the new record at your DNS provider and **Verify a Domain** again. The response is the same domain object as **Get a Domain**. **Notes** - `tracking_prefix` is the tracking / Return-Path host (`mc` in `mc.example.com`). It cannot be changed for a subdomain. - For a subdomain, the image record's host is on the root domain (e.g. `img2.example.com` for `news.example.com`). - The DKIM and second DKIM selectors must be different. operationId: update-a-domain parameters: - name: id in: path required: true description: Domain ID (from Add a Domain or List Domains) schema: type: string requestBody: required: true content: application/json: schema: type: object properties: tracking_prefix: type: string description: |- New host label of the `tracking` record. Letters and digits only. Maximum: 25 Main domains only (not subdomains). maxLength: 25 dkim_selector: type: string description: >- New selector of the `dkim` record (`._domainkey.`). Letters and digits only. Maximum: 3 maxLength: 3 dkim2_selector: type: string description: |- New selector of the `dkim2` record. Letters and digits only. Maximum: 3 maxLength: 3 image_prefix: type: string description: |- New host label of the `image` record. Letters, digits and dots. Maximum: 25 maxLength: 25 open_tracking: type: boolean description: >- Turn open tracking on (`true`) or off (`false`) — the same as the open-tracking toggle in the app. No effect on marketing campaigns. examples: Rename DKIM: value: dkim_selector: k3 Several changes: value: dkim_selector: k3 image_prefix: img2 open_tracking: true Open tracking only: value: open_tracking: false responses: '200': description: OK 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' Failed: value: id: zjAKXb domain: example.com status: failed open_tracking: false records: - type: CNAME host: mc.example.com value: mc3035n.mlrcloud.com status: verified purpose: tracking - type: CNAME host: k1._domainkey.example.com value: dkim.mlrcloud.com status: verified purpose: dkim - 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: verified purpose: image - 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: invalid purpose: dmarc message: Edit and update the record in your domain provider error_message: More than one dmarc TXT record found in your provider created_at: '2026-10-13 15:13:00' '400': description: Bad Request — invalid input; nothing was changed content: application/json: schema: type: object properties: errors: type: array items: type: object properties: field: type: string message: type: string examples: Nothing sent: value: errors: - field: '' message: >- Send at least one of tracking_prefix, dkim_selector, dkim2_selector, image_prefix, open_tracking Invalid label: value: errors: - field: image_prefix message: Only letters, numbers, and dots are allowed Too long: value: errors: - field: dkim_selector message: Maximum length is 3 characters Subdomain: value: errors: - field: tracking_prefix message: Tracking prefix can't be changed for a subdomain Same selector: value: errors: - field: dkim2_selector message: Selector already used by the other DKIM record Invalid JSON: value: errors: - field: '' message: Invalid json format '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 '404': description: Not Found — unknown id, or a domain that belongs to another account 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: id message: Domain not found '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.