Domains

Manage domains, DNS records and verification for email sending

Register domains for email sending, manage DNS records required for authentication, and verify your domain settings. Each added domain includes automatically generated DNS records for proper email delivery.

Add Domain

Register a new domain for email sending with automatically generated DNS records.

Request Header

POST https://api.cm.com/email/configuration/v1/configuration
Content-Type: application/json
Header NameTypeRequiredDescription
Content-TypestringYesMust be "application/json"

Request Body

{
  "emailAddress": "[email protected]",
  "domain": "example.com",
  "accountId": "903e1cef-84b3-4500-a9a5-b2ca219f76f5",
  "dnsRecords": [
    {
      "host": "cm2903e1cef84b34500a9a5b2ca219f76f5._domainkey.example.com",
      "type": "CNAME", 
      "value": "903e1cef84b34500a9a5b2ca219f76f5cm2._domainkey.email.cm.com.",
      "isValid": false
    },
    {
      "host": "cm903e1cef84b34500a9a5b2ca219f76f5.example.com",
      "type": "CNAME",
      "value": "903e1cef84b34500a9a5b2ca219f76f5.email.cm.com.",
      "isValid": false
    },
    {
      "host": "cm1903e1cef84b34500a9a5b2ca219f76f5._domainkey.example.com", 
      "type": "CNAME",
      "value": "903e1cef84b34500a9a5b2ca219f76f5cm1._domainkey.email.cm.com.",
      "isValid": false
    }
  ]
}

Response Body

Successful Response (200)

{
    "status": 200,
    "message": "Success",
    "success": true,
    "domainConfig": {
        "id": 97,
        "accountId": "903e1fcf-84b3-4511-a9a5-b2cb219f76f5",
        "domain": "xyz.com",
        "createdOn": "2025-10-16T10:41:24.432089Z",
        "modifiedOn": null,
        "deletedOn": null,
        "dnsRecords": [],
        "isValid": false
    }
}

Error Responses

Invalid Request (400)

{
  "status": 400,
  "message": "Invalid Address",
  "success": false,
  "domainConfig": null
}

Invalid Account (400)

{
  "status": 400,
  "message": "Invalid Account Id token",
  "success": false,
  "domainConfig": null
}

Internal Error (500)

{
  "status": 500,
  "message": "Failed to create domain",
  "success": false,
  "domainConfig": null
}

Get Domains

Retrieve all domain configurations for a specific logical account.

Request Header

GET https://api.cm.com/email/configuration/v1/configuration/accounts/{logicalAccountId}
ParameterTypeRequiredDescription
logicalAccountIdUUIDYesThe logical account identifier

Response Body

Successful Response (200)

{
    "status": 200,
    "message": "Success",
    "success": true,
    "domains": [
        {
            "id": 97,
            "accountId": "73f79df6-d256-4d8d-ba0c-354fee8987b2",
            "domain": "xyz.com",
            "createdOn": "2025-10-16T10:41:24.432089",
            "modifiedOn": null,
            "deletedOn": null,
            "dnsRecords": [
                {
                    "host": "cm273f79df6d2564d8dba0c354fee8987b2._domainkey.xyz.com",
                    "type": "CNAME",
                    "value": "73f79df6d2564d8dba0c354fee8987b2cm2._domainkey.email.cmtest.nl."
                },
                {
                    "host": "cm73f79df6d2564d8dba0c354fee8987b2.xyz.com",
                    "type": "CNAME",
                    "value": "73f79df6d2564d8dba0c354fee8987b2.email.cmtest.nl."
                },
                {
                    "host": "cm173f79df6d2564d8dba0c354fee8987b2._domainkey.xyz.com",
                    "type": "CNAME",
                    "value": "73f79df6d2564d8dba0c354fee8987b2cm1._domainkey.email.cmtest.nl."
                }
            ],
            "isValid": false
        },
        {
            "id": 94,
            "accountId": "903e1cef-84b3-4500-a9a5-b2ca219f76f5",
            "domain": "abc.com",
            "createdOn": "2025-10-14T12:35:05.728919",
            "modifiedOn": null,
            "deletedOn": null,
            "dnsRecords": [
                {
                    "host": "cm2903e1cef84b34500a9a5b2ca219f76f5._domainkey.nl.com",
                    "type": "CNAME",
                    "value": "903e1cef84b34500a9a5b2ca219f76f5cm2._domainkey.email.cmtest.nl."
                },
                {
                    "host": "cm903e1cef84b34500a9a5b2ca219f76f5.nl.com",
                    "type": "CNAME",
                    "value": "903e1cef84b34500a9a5b2ca219f76f5.email.cmtest.nl."
                },
                {
                    "host": "cm1903e1cef84b34500a9a5b2ca219f76f5._domainkey.nl.com",
                    "type": "CNAME",
                    "value": "903e1cef84b34500a9a5b2ca219f76f5cm1._domainkey.email.cmtest.nl."
                }
            ],
            "isValid": false
        }
    ]
}

Error Responses

Invalid Logical Account - Error Response (400)

{
  "status": 400,
  "message": "Invalid accountId. AccountId cannot be empty",
  "domains": [],
  "success": false
}

Internal Error - Error Response (500)

{
  "status": 500,
  "message": "Unable to get the domain config",
  "domains": [],
  "success": false
}

Get DNS Records

Retrieve DNS records for a specific domain within an account.

Request Header

GET https://api.cm.com/email/configuration/v1/configuration/accounts/{logicalAccountId}/domains/{domainId}
ParameterTypeRequiredDescription
logicalAccountIdUUIDYesThe logical account identifier
domainIdintegerYesThe domain identifier

Response Body

Successful Response (200)

{
    "status": 200,
    "message": "Success",
    "success": true,
    "dnsRecords": [
        {
            "id": 223,
            "fromDomain": 97,
            "host": "cm2903e1cef84b34500a9a5b2ca219f76f5._domainkey.xyz.com",
            "type": "CNAME",
            "value": "903e1cef84b34500a9a5b2ca219f76f5cm2._domainkey.email.cmtest.nl.",
            "isValid": false
        },
        {
            "id": 224,
            "fromDomain": 97,
            "host": "cm903e1cef84b34500a9a5b2ca219f76f5.xyz.com",
            "type": "CNAME",
            "value": "903e1cef84b34500a9a5b2ca219f76f5.email.cmtest.nl.",
            "isValid": false
        },
        {
            "id": 225,
            "fromDomain": 97,
            "host": "cm1903e1cef84b34500a9a5b2ca219f76f5._domainkey.xyz.com",
            "type": "CNAME",
            "value": "903e1cef84b34500a9a5b2ca219f76f5cm1._domainkey.email.cmtest.nl.",
            "isValid": false
        }
    ]
}

Error Responses

Error Response (404)

{
  "status": 404,
  "message": "Unable to fetch DNS records",
  "success": false
}

Delete Domain

Remove a domain configuration and all associated DNS records.

Request Header

DELETE https://api.cm.com/email/configuration/v1/configuration/accounts/{logicalAccountId}/domains/{domainId}
ParameterTypeRequiredDescription
domainIdintegerYesThe domain identifier to delete

Response Body

Successful Response (200)

{
  "status": 200, 
  "message": "Success",
  "success": true
}

Error Responses

Invalid Domain ID (400)

{
  "status": 400,
  "message": "Unable to delete the domain",
  "success": false
}

Domain Not Found (404)

{
  "status": 404, 
  "message": "Invalid domainId. Domain not found",
  "success": false
}

Verify Domain Configuration

Verify domain ownership and DNS record configuration to ensure proper email delivery setup.

Request Header

POST https://api.cm.com/email/configuration/v1/dns/accounts/{logicalAccountId}/verify?domain={domain}
Content-Type: application/json
ParameterTypeRequiredDescription
logicalAccountIdUUIDYesThe logical account identifier
ParameterTypeRequiredDescription
domainstringYesDomain name to verify (e.g., "example.com")
Header NameTypeRequiredDescription
AuthorizationstringYesValid authorization token

Response Body

Successful Response (200)

{
    "status": 200,
    "message": "Success",
    "success": true,
    "dnsEntries": [
        {
            "host": "cm903e1cef84b34500a9a5b2ca219f76f5.xyz.com",
            "value": "903e1cef84b34500a9a5b2ca219f76f5.email.cmtest.nl.",
            "isValid": false,
            "type": "CNAME"
        },
        {
            "host": "cm1903e1cef84b34500a9a5b2ca219f76f5._domainkey.xyz.com",
            "value": "903e1cef84b34500a9a5b2ca219f76f5cm1._domainkey.email.cmtest.nl.",
            "isValid": false,
            "type": "CNAME"
        },
        {
            "host": "cm2903e1cef84b34500a9a5b2ca219f76f5._domainkey.xyz.com",
            "value": "903e1cef84b34500a9a5b2ca219f76f5cm2._domainkey.email.cmtest.nl.",
            "isValid": false,
            "type": "CNAME"
        }
    ]
}

Partial Verification Response (200)

When some DNS records are not yet properly configured:

{
    "status": 200,
    "message": "Success",
    "success": true,
    "dnsEntries": [
        {
            "host": "cm903e1cef84b34500a9a5b2ca219f76f5.xyz.com",
            "value": "903e1cef84b34500a9a5b2ca219f76f5.email.cmtest.nl.",
            "isValid": false,
            "type": "CNAME"
        },
        {
            "host": "cm1903e1cef84b34500a9a5b2ca219f76f5._domainkey.xyz.com",
            "value": "903e1cef84b34500a9a5b2ca219f76f5cm1._domainkey.email.cmtest.nl.",
            "isValid": true,
            "type": "CNAME"
        },
        {
            "host": "cm2903e1cef84b34500a9a5b2ca219f76f5._domainkey.xyz.com",
            "value": "903e1cef84b34500a9a5b2ca219f76f5cm2._domainkey.email.cmtest.nl.",
            "isValid": false,
            "type": "CNAME"
        }
    ]
}

Error Responses

Domain Verification Failed (400)

{
  "status": 400,
  "message": "unable to verify domain",
  "success": false,
  "dnsEntries": []
}

Unauthorized Access (401)

{
  "status": 401,
  "message": "Access denied - insufficient permissions",
  "success": false,
  "dnsEntries": []
}

Domain Not Found (400)

{
  "status": 401,
  "essage": "Domain not found or not configured for this account",
  "success": false,
  "dnsEntries": []
}

Domain Verification Process

  1. Add Domain: Submit domain configuration with your account ID
  2. DNS Records Generated: System automatically creates three CNAME records
  3. Add DNS Records: Add the generated CNAME records to your domain's DNS settings
  4. Wait for Propagation: Allow time for DNS changes to propagate (5 minutes to 48 hours)
  5. Verify Domain: Use the verification endpoint to check DNS record configuration
  6. Check Results: Review verification response to see which records are valid
  7. Retry if Needed: Re-run verification after additional propagation time if some records show as invalid
  8. Email Sending: Domain is ready for email sending once all records show "isValid": true

Common Issues and Solutions

IssueCauseSolution
All records show isValid: falseDNS records not yet added or propagatedWait for DNS propagation (5 min - 48 hours) and retry
Some records valid, others invalidPartial DNS configuration or cachingCheck DNS provider settings and wait for full propagation
Verification endpoint returns 400Domain not found in accountEnsure domain was properly added to account first

Example Use Cases

Register Company Domain

Setting up a primary company domain for email sending:

{
  "emailAddress": "[email protected]",
  "domain": "company.com",
  "accountId": "903e1cef-84b3-4500-a9a5-b2ca219f76f5",
  "dnsRecords": [
    {
      "host": "cm2903e1cef84b34500a9a5b2ca219f76f5._domainkey.company.com",
      "type": "CNAME",
      "value": "903e1cef84b34500a9a5b2ca219f76f5cm2._domainkey.email.cm.com.",
      "isValid": false
    },
    {
      "host": "cm903e1cef84b34500a9a5b2ca219f76f5.company.com",
      "type": "CNAME",
      "value": "903e1cef84b34500a9a5b2ca219f76f5.email.cm.com.",
      "isValid": false
    },
    {
      "host": "cm1903e1cef84b34500a9a5b2ca219f76f5._domainkey.company.com",
      "type": "CNAME",
      "value": "903e1cef84b34500a9a5b2ca219f76f5cm1._domainkey.email.cm.com.",
      "isValid": false
    }
  ]
}

Add Subdomain for Marketing

Adding a subdomain specifically for marketing campaigns:

{
  "emailAddress": "[email protected]",
  "domain": "marketing.company.com", 
  "accountId": "903e1cef-84b3-4500-a9a5-b2ca219f76f5",
  "dnsRecords": [
    {
      "host": "cm2903e1cef84b34500a9a5b2ca219f76f5._domainkey.marketing.company.com",
      "type": "CNAME",
      "value": "903e1cef84b34500a9a5b2ca219f76f5cm2._domainkey.email.cm.com.",
      "isValid": false
    },
    {
      "host": "cm903e1cef84b34500a9a5b2ca219f76f5.marketing.company.com",
      "type": "CNAME",
      "value": "903e1cef84b34500a9a5b2ca219f76f5.email.cm.com.",
      "isValid": false
    },
    {
      "host": "cm1903e1cef84b34500a9a5b2ca219f76f5._domainkey.marketing.company.com",
      "type": "CNAME", 
      "value": "903e1cef84b34500a9a5b2ca219f76f5cm1._domainkey.email.cm.com.",
      "isValid": false
    }
  ]
}

Multi-Domain Setup

Managing multiple domains for different business units:

  1. Main Website: company.com
  2. Support Portal: support.company.com
  3. Marketing Campaigns: promo.company.com
  4. Customer Portal: portal.company.com

Each domain will receive the same three CNAME records (with domain-specific hostnames) but pointing to the same account-specific email infrastructure, ensuring consistent email delivery across all business units.