Domains

Our Email Configuration API enables developers to manage email domains and DNS records for their email sending infrastructure. The API provides comprehensive domain management capabilities including domain registration, verification, and DNS record management.

Permissions Required

To access Email Configuration API endpoints, the user must have valid permissions associated with their account:

EmailConfiguration_Create - Required for creating domain configurations
EmailConfiguration_Read - Required for reading domain configurations and DNS records
EmailConfiguration_Delete - Required for deleting domain configurations

Fact Sheet

Feature	Support	Remark
Domain Registration	Yes	Register domains for email sending with automatic DNS record generation
DNS Record Management	Yes	Manage DKIM, SPF, and other DNS records required for email authentication
Domain Verification	Yes	Verify domain ownership through DNS record validation
Multiple Domains per Account	Yes	Support for multiple domains under a single logical account
Domain Deletion	Yes	Remove domains and associated DNS records
Account-based Organization	Yes	Domains are organized by logical account IDs

Managing Email Domains

The Email Configuration API allows you to register domains for email sending, manage DNS records required for email authentication, and verify domain ownership. Each domain is associated with a logical account and includes automatically generated DNS records for proper email delivery.

Domain Configuration

Add Domain Configuration

POST https://api.cm.com/email/configuration/v1/configuration
Content-Type: application/json

Request Headers

Header Name	Type	Required	Description
Content-Type	string	Yes	Must be "application/json"
Authorization	string	Yes	Valid authorization token

Request Body Example

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

Successful Response (200)

{
  "statusCode": "Ok",
  "statusMessage": "Success",
  "domainConfig": {
    "id": 123,
    "domain": "example.com",
    "accountId": "903e1cef-84b3-4500-a9a5-b2ca219f76f5",
    "isValid": false,
    "createdOn": "2024-03-15T10:30:00Z",
    "modifiedOn": null,
    "deletedOn": null,
    "dnsRecords": [
      {
        "host": "cm2903e1cef84b34500a9a5b2ca219f76f5._domainkey.example.com",
        "type": "CNAME",
        "value": "903e1cef84b34500a9a5b2ca219f76f5cm2._domainkey.email.cmtest.nl.",
        "isValid": false
      },
      {
        "host": "cm903e1cef84b34500a9a5b2ca219f76f5.example.com",
        "type": "CNAME",
        "value": "903e1cef84b34500a9a5b2ca219f76f5.email.cmtest.nl.",
        "isValid": false
      },
      {
        "host": "cm1903e1cef84b34500a9a5b2ca219f76f5._domainkey.example.com",
        "type": "CNAME",
        "value": "903e1cef84b34500a9a5b2ca219f76f5cm1._domainkey.email.cmtest.nl.",
        "isValid": false
      }
    ]
  }
}

Error Responses

Invalid Request (400)

{
  "statusCode": "InvalidRequest", 
  "statusMessage": "Domain cannot be empty or null",
  "domainConfig": null
}

Invalid Account (400)

{
  "statusCode": "InvalidRequest",
  "statusMessage": "Invalid AccountId Token", 
  "domainConfig": null
}

Not Found (404)

{
  "statusCode": "NotFound",
  "statusMessage": "Resource not found",
  "domainConfig": null
}

Get Domain Configurations by Account

Retrieve all domain configurations for a specific logical account.

GET https://api.cm.com/email/configuration/v1/configuration/accounts/{logicalAccountId}

Path Parameters

Parameter	Type	Required	Description
logicalAccountId	UUID	Yes	The logical account identifier

Successful Response (200)

{
  "statusCode": "Ok",
  "statusMessage": "Success", 
  "domains": [
    {
      "id": 123,
      "domain": "example.com", 
      "accountId": "903e1cef-84b3-4500-a9a5-b2ca219f76f5",
      "isValid": true,
      "createdOn": "2024-03-15T10:30:00Z",
      "modifiedOn": "2024-03-16T14:20:00Z",
      "deletedOn": null,
      "dnsRecords": [
        {
          "host": "cm2903e1cef84b34500a9a5b2ca219f76f5._domainkey.example.com",
          "type": "CNAME",
          "value": "903e1cef84b34500a9a5b2ca219f76f5cm2._domainkey.email.cmtest.nl.",
          "isValid": true
        },
        {
          "host": "cm903e1cef84b34500a9a5b2ca219f76f5.example.com",
          "type": "CNAME",
          "value": "903e1cef84b34500a9a5b2ca219f76f5.email.cmtest.nl.",
          "isValid": true
        },
        {
          "host": "cm1903e1cef84b34500a9a5b2ca219f76f5._domainkey.example.com",
          "type": "CNAME",
          "value": "903e1cef84b34500a9a5b2ca219f76f5cm1._domainkey.email.cmtest.nl.",
          "isValid": true
        }
      ]
    }
  ]
}

Error Response (400)

{
  "statusCode": "InvalidRequest",
  "statusMessage": "Invalid request parameters",
  "domains": []
}

Get DNS Records by Domain

Retrieve DNS records for a specific domain within an account.

GET https://api.cm.com/email/configuration/v1/configuration/dns/accounts/{logicalAccountId}/domains/{domainId}

Path Parameters

Parameter	Type	Required	Description
logicalAccountId	UUID	Yes	The logical account identifier
domainId	integer	Yes	The domain identifier

Successful Response (200)

{
  "statusCode": "Ok",
  "statusMessage": "Success",
  "dnsRecords": [
    {
      "id": 456,
      "fromDomain": 123,
      "host": "cm2903e1cef84b34500a9a5b2ca219f76f5._domainkey.example.com",
      "type": "CNAME", 
      "value": "903e1cef84b34500a9a5b2ca219f76f5cm2._domainkey.email.cmtest.nl.",
      "isValid": true
    },
    {
      "id": 457,
      "fromDomain": 123,
      "host": "cm903e1cef84b34500a9a5b2ca219f76f5.example.com",
      "type": "CNAME",
      "value": "903e1cef84b34500a9a5b2ca219f76f5.email.cmtest.nl.", 
      "isValid": true
    },
    {
      "id": 458,
      "fromDomain": 123,
      "host": "cm1903e1cef84b34500a9a5b2ca219f76f5._domainkey.example.com",
      "type": "CNAME",
      "value": "903e1cef84b34500a9a5b2ca219f76f5cm1._domainkey.email.cmtest.nl.",
      "isValid": true
    }
  ]
}

Error Response (404)

{
  "statusCode": "NotFound",
  "statusMessage": "DNS records not found for the specified domain"
}

Delete Domain Configuration

Remove a domain configuration and all associated DNS records.

DELETE https://api.cm.com/email/configuration/v1/configuration/dns/domains/{domainId}

Path Parameters

Parameter	Type	Required	Description
domainId	integer	Yes	The domain identifier to delete

Successful Response (200)

{
  "statusCode": "Ok", 
  "statusMessage": "Domain deleted successfully"
}

Error Responses

Invalid Domain ID (400)

{
  "statusCode": "InvalidRequest",
  "statusMessage": "Invalid request parameters"
}

Domain Not Found (404)

{
  "statusCode": "NotFound", 
  "statusMessage": "Domain not found"
}

Verify Domain Configuration

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

POST https://api.cm.com/email/configuration/v1/dns/accounts/{logicalAccountId}/verify?domain={domain}
Content-Type: application/json

Path Parameters

Parameter	Type	Required	Description
logicalAccountId	UUID	Yes	The logical account identifier

Query Parameters

Parameter	Type	Required	Description
domain	string	Yes	Domain name to verify (e.g., "example.com")

Request Headers

Header Name	Type	Required	Description
Authorization	string	Yes	Valid authorization token

Successful Response (200)

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

Partial Verification Response (200)

When some DNS records are not yet properly configured:

{
  "statusCode": "Ok",
  "message": "Success",
  "dnsEntries": [
    {
      "host": "cm2903e1cef84b34500a9a5b2ca219f76f5._domainkey.example.com",
      "type": "CNAME",
      "value": "903e1cef84b34500a9a5b2ca219f76f5cm2._domainkey.email.cmtest.nl.",
      "isValid": false
    },
    {
      "host": "cm903e1cef84b34500a9a5b2ca219f76f5.example.com",
      "type": "CNAME",
      "value": "903e1cef84b34500a9a5b2ca219f76f5.email.cmtest.nl.",
      "isValid": false
    },
    {
      "host": "cm1903e1cef84b34500a9a5b2ca219f76f5._domainkey.example.com",
      "type": "CNAME",
      "value": "903e1cef84b34500a9a5b2ca219f76f5cm1._domainkey.email.cmtest.nl.",
      "isValid": false
    }
  ]
}

Error Responses

Domain Verification Failed (400)

{
  "statusCode": "InvalidRequest",
  "message": "unable to verify domain",
  "dnsEntries": []
}

Unauthorized Access (401)

{
  "statusCode": "Unauthorized",
  "message": "Access denied - insufficient permissions",
  "dnsEntries": []
}

Domain Not Found (400)

{
  "statusCode": "InvalidRequest", 
  "message": "Domain not found or not configured for this account",
  "dnsEntries": []
}

Domain Verification Process Details

Verification Steps

Current Status Check: System retrieves the current verification status of the domain
DNS Record Lookup: Performs DNS queries to check if CNAME records are properly configured
Record Validation: Compares actual DNS values with expected values for your account
Database Update: Updates the verification status of each DNS record in the system
Notification: Sends notifications if domain verification status has changed
Response: Returns detailed verification results for each DNS record

DNS Entry Object

Field	Type	Description
host	string	DNS record hostname that was verified
type	string	DNS record type (always "CNAME")
value	string	Expected DNS record value for verification
isValid	boolean	Whether this specific DNS record is correctly configured

Updated Domain Verification Process

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

Verification Example Use Cases

Initial Domain Verification

Check if newly added DNS records are properly configured:

POST https://api.cm.com/email/configuration/v1/dns/accounts/903e1cef-84b3-4500-a9a5-b2ca219f76f5/verify?domain=company.com

Updated Best Practices

Domain Verification: Always add all three generated CNAME records to your domain's DNS settings for proper verification
DNS Propagation: Allow 24-48 hours for DNS changes to propagate globally before considering verification failed
Regular Verification: Periodically verify domains to ensure DNS records remain properly configured
Account Organization: Group related domains under the same logical account for easier management
Cache Awareness: Remember that DNS caching at multiple levels can delay verification results

Common Issues and Solutions

Issue	Cause	Solution
All records show `isValid: false`	DNS records not yet added or propagated	Wait for DNS propagation (5 min - 48 hours) and retry
Some records valid, others invalid	Partial DNS configuration or caching	Check DNS provider settings and wait for full propagation
Verification endpoint returns 400	Domain not found in account	Ensure domain was properly added to account first

DNS Record Generation

The system automatically generates DNS records based on your logical account ID. The account ID undergoes the following transformation:

Original Account ID: 903e1cef-84b3-4500-a9a5-b2ca219f76f5
Processed Account ID: 903e1cef84b34500a9a5b2ca219f76f5 (dashes removed)
Generated Records: Three CNAME records are created for each domain

DNS Record Pattern

For domain example.com with account ID 903e1cef-84b3-4500-a9a5-b2ca219f76f5:

Record Type	Host	Value
CNAME	`cm2903e1cef84b34500a9a5b2ca219f76f5._domainkey.example.com`	`903e1cef84b34500a9a5b2ca219f76f5cm2._domainkey.email.cmtest.nl.`
CNAME	`cm903e1cef84b34500a9a5b2ca219f76f5.example.com`	`903e1cef84b34500a9a5b2ca219f76f5.email.cmtest.nl.`
CNAME	`cm1903e1cef84b34500a9a5b2ca219f76f5._domainkey.example.com`	`903e1cef84b34500a9a5b2ca219f76f5cm1._domainkey.email.cmtest.nl.`

Request Parameters

Domain Configuration Request Body Fields

Field	Type	Required	Description
emailAddress	string	Yes	Email address for notifications
domain	string	Yes	Domain name to configure (e.g., "example.com")
accountId	UUID	Yes	Logical account identifier
dnsRecords	array	Yes	Array of DNS record objects (auto-generated)

DNS Record Object

Field	Type	Required	Description
host	string	Yes	DNS record hostname (auto-generated)
type	string	Yes	DNS record type (always "CNAME")
value	string	Yes	DNS record value (auto-generated)
isValid	boolean	Yes	Validation status (initially false)

DNS Record Types

Type	Description	Purpose
CNAME	Canonical name records	Email authentication and routing

All DNS records are automatically generated as CNAME records pointing to the email service infrastructure.

Status Codes

Status Code	Description
200	OK: Request processed successfully
400	Bad Request: Invalid request data or parameters
404	Not Found: Requested resource not found
500	Internal Server Error: Server-side error

Error Handling

All error responses follow a consistent format:

{
  "statusCode": "ErrorCode",
  "statusMessage": "Human-readable error description",
  "domainConfig": null
}

Best Practices

Domain Verification: Always add all three generated CNAME records to your domain's DNS settings for proper verification
DNS Propagation: Allow 24-48 hours for DNS changes to propagate globally
Account Organization: Group related domains under the same logical account for easier management

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.cmtest.nl.",
      "isValid": false
    },
    {
      "host": "cm903e1cef84b34500a9a5b2ca219f76f5.company.com",
      "type": "CNAME",
      "value": "903e1cef84b34500a9a5b2ca219f76f5.email.cmtest.nl.",
      "isValid": false
    },
    {
      "host": "cm1903e1cef84b34500a9a5b2ca219f76f5._domainkey.company.com",
      "type": "CNAME",
      "value": "903e1cef84b34500a9a5b2ca219f76f5cm1._domainkey.email.cmtest.nl.",
      "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.cmtest.nl.",
      "isValid": false
    },
    {
      "host": "cm903e1cef84b34500a9a5b2ca219f76f5.marketing.company.com",
      "type": "CNAME",
      "value": "903e1cef84b34500a9a5b2ca219f76f5.email.cmtest.nl.",
      "isValid": false
    },
    {
      "host": "cm1903e1cef84b34500a9a5b2ca219f76f5._domainkey.marketing.company.com",
      "type": "CNAME", 
      "value": "903e1cef84b34500a9a5b2ca219f76f5cm1._domainkey.email.cmtest.nl.",
      "isValid": false
    }
  ]
}

Multi-Domain Setup

Managing multiple domains for different business units:

Main Website: company.com
Support Portal: support.company.com
Marketing Campaigns: promo.company.com
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.

DNS Records You Need to Add

After registering a domain, add these CNAME records to your DNS provider (Make sure you are at DNS records inside yourdomain.com):

cm2903e1cef84b34500a9a5b2ca219f76f5._domainkey → 903e1cef84b34500a9a5b2ca219f76f5cm2._domainkey.email.cmtest.nl.
cm903e1cef84b34500a9a5b2ca219f76f5 → 903e1cef84b34500a9a5b2ca219f76f5.email.cmtest.nl.
cm1903e1cef84b34500a9a5b2ca219f76f5._domainkey → 903e1cef84b34500a9a5b2ca219f76f5cm1._domainkey.email.cmtest.nl.