---
title: "Set Up Domain"
method: POST
path: "/v1/domains/setup"
tags: ["Domains"]
---

# Set Up Domain

`POST /v1/domains/setup`

Provision the main sending identity (bare root domain) and notify.<rootDomain> (transactional) on a domain you own in one call. The main identity is used for campaigns and hand sends; notify.<rootDomain> is for receipts and password resets. If a legacy send.<rootDomain> marketing identity already exists, it is included in the response; new setups do not create marketing. Idempotent. Safe to call again if DNS records already exist. Returns DNS records for each provisioned identity. Requires API key with domains:write.

## Request body

- object
  - `rootDomain` string, required — The apex domain you own, e.g. 'acme.com'
  - `fromName` string — Default From display name for provisioned identities.
  - `vanityRootFrom` boolean — Show the apex domain in the From header when DMARC passes. Defaults to true.

## Response `200`

Domain setup complete

- object
  - `success` boolean
  - `data` SetupDomainResult
    - `main` SendingDomain, required
      - `_id` string
      - `domain` string
      - `region` 'us-east-1' | 'eu-west-1' | 'us-east-2' — AWS region the domain sends from. Automatically assigned at creation.
      - `regionName` string
      - `status` 'pending' | 'verifying' | 'verified' | 'degraded' | 'failed' | 'suspended'
      - `dkimStatus` 'SUCCESS' | 'PENDING' | 'FAILED' | 'NOT_STARTED'
      - `mailFromDomain` string
      - `mailFromStatus` 'SUCCESS' | 'PENDING' | 'FAILED'
      - `dnsRecords` DnsRecord[]
        - `type` 'CNAME' | 'TXT' | 'MX'
        - `name` string
        - `value` string
        - `priority` integer
        - `status` 'pending' | 'verified' | 'failed'
      - `ownershipVerified` boolean
      - `openTracking` boolean
      - `clickTracking` boolean
      - `brandedTracking` boolean
      - `createdAt` string, date-time
      - `verifiedAt` string, date-time, nullable
      - `isManagedDomain` boolean
    - `transactional` SendingDomain, required
      - `_id` string
      - `domain` string
      - `region` 'us-east-1' | 'eu-west-1' | 'us-east-2' — AWS region the domain sends from. Automatically assigned at creation.
      - `regionName` string
      - `status` 'pending' | 'verifying' | 'verified' | 'degraded' | 'failed' | 'suspended'
      - `dkimStatus` 'SUCCESS' | 'PENDING' | 'FAILED' | 'NOT_STARTED'
      - `mailFromDomain` string
      - `mailFromStatus` 'SUCCESS' | 'PENDING' | 'FAILED'
      - `dnsRecords` DnsRecord[]
        - `type` 'CNAME' | 'TXT' | 'MX'
        - `name` string
        - `value` string
        - `priority` integer
        - `status` 'pending' | 'verified' | 'failed'
      - `ownershipVerified` boolean
      - `openTracking` boolean
      - `clickTracking` boolean
      - `brandedTracking` boolean
      - `createdAt` string, date-time
      - `verifiedAt` string, date-time, nullable
      - `isManagedDomain` boolean
    - `marketing` SendingDomain
      - `_id` string
      - `domain` string
      - `region` 'us-east-1' | 'eu-west-1' | 'us-east-2' — AWS region the domain sends from. Automatically assigned at creation.
      - `regionName` string
      - `status` 'pending' | 'verifying' | 'verified' | 'degraded' | 'failed' | 'suspended'
      - `dkimStatus` 'SUCCESS' | 'PENDING' | 'FAILED' | 'NOT_STARTED'
      - `mailFromDomain` string
      - `mailFromStatus` 'SUCCESS' | 'PENDING' | 'FAILED'
      - `dnsRecords` DnsRecord[]
        - `type` 'CNAME' | 'TXT' | 'MX'
        - `name` string
        - `value` string
        - `priority` integer
        - `status` 'pending' | 'verified' | 'failed'
      - `ownershipVerified` boolean
      - `openTracking` boolean
      - `clickTracking` boolean
      - `brandedTracking` boolean
      - `createdAt` string, date-time
      - `verifiedAt` string, date-time, nullable
      - `isManagedDomain` boolean

## Other responses

- `400` — Bad request
- `401` — Unauthorized

## Changes

- **2026-08-31** `6b3357db6cf6` — 3 info
  - added the optional property `data/marketing` to the response with the `200` status
  - added the required property `data/main` to the response with the `200` status
  - added the required property `data/transactional` to the response with the `200` status
- **2026-07-26** `3f3dba69574b` — 1 warning
  - removed the request property `region`

[Change history](https://skmtc.dev/migma/apis/migma-ai-api-v1/changes/v1/domains/setup/post.md)

---

[API](https://skmtc.dev/migma/apis/migma-ai-api-v1.md) · [All operations](https://skmtc.dev/migma/apis/migma-ai-api-v1/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/migma/migma-ai-api-v1/revisions/6b3357db6cf6/schema)