Custom Domains API

Configure and verify a custom tracking domain for your organization to improve email deliverability.

Get Domain

Retrieve the current custom domain configuration.

Endpoint


GET /api/organizations/domain

Example Request


curl -X GET NEXT_PUBLIC_BASE_URL/api/organizations/domain \
  -H "x-api-key: your-api-key"

Response Schema

Field	Type	Description
`customDomain`	`string \| null`	Configured domain or null if not set
`domainVerified`	`boolean`	Whether the domain has been verified
`domainVerifiedAt`	`string \| null`	ISO 8601 timestamp of verification
`expectedCNAME`	`string`	CNAME target value for DNS setup

Example Response


{
  "customDomain": "track.example.com",
  "domainVerified": true,
  "domainVerifiedAt": "2024-03-15T12:00:00.000Z",
  "expectedCNAME": "mailpulse-io.lyten.agency"
}

Set Domain

Configure a custom tracking domain for your organization.

Endpoint


POST /api/organizations/domain

Request Body

Field	Type	Required	Description
`domain`	`string`	Yes	Subdomain to use for tracking (e.g. `track.example.com`)

Example Request


curl -X POST NEXT_PUBLIC_BASE_URL/api/organizations/domain \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "track.example.com"
  }'

Example Response


{
  "customDomain": "track.example.com",
  "domainVerified": false
}

Remove Domain

Remove the custom tracking domain from your organization.

Endpoint


DELETE /api/organizations/domain

Example Request


curl -X DELETE NEXT_PUBLIC_BASE_URL/api/organizations/domain \
  -H "x-api-key: your-api-key"

Example Response


{
  "success": true
}

Verify Domain

Trigger a DNS verification check for your configured domain.

Endpoint


POST /api/organizations/domain/verify

Example Request


curl -X POST NEXT_PUBLIC_BASE_URL/api/organizations/domain/verify \
  -H "x-api-key: your-api-key"

Example Response (Success)


{
  "verified": true,
  "domainVerifiedAt": "2024-03-15T12:00:00.000Z"
}

Example Response (Failure)


{
  "verified": false,
  "error": "CNAME record not found"
}

CNAME Setup

To verify your custom domain, add a CNAME record with your DNS provider:

Type	Name	Value
`CNAME`	Your subdomain (e.g. `track`)	`mailpulse-io.lyten.agency`

DNS propagation can take up to 48 hours. Once the record is in place, call the verify endpoint to complete the setup.

Error Responses

Status	Description
`401 Unauthorized`	Invalid or missing API key
`400 Bad Request`	Invalid domain format or domain already in use

Example Error


{
  "error": "Invalid domain format"
}