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 /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 /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 /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 /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"
}

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
}

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
Verification: System validates the DNS records (isValid becomes true)
Email Sending: Domain is ready for email sending once verified

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:

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

Replace yourdomain.com with your actual domain and use the exact values provided in the API response.