Pro Domains

Add your own custom domains to receive emails. Requires DNS verification.

List Custom Domains

GET /pro/api/domains

Request

curl https://api.mail.cx/pro/api/domains \
  -H "Authorization: Bearer tm_pro_xxxxxxxxxxxx"

Response 200

{
  "domains": [
    {
      "id": "d1e2f3a4-b5c6-7890-def1-234567890abc",
      "domain": "yourdomain.com",
      "verify_status": "verified",
      "verify_token": "mailcx-verify-abc123",
      "verified_at": "2025-01-15T12:00:00Z",
      "mx_configured": true,
      "created_at": "2025-01-15T10:00:00Z"
    }
  ]
}

Domain Fields

Field	Type	Description
id	uuid	Domain ID
domain	string	Domain name
verify_status	string	pending or verified
verify_token	string	TXT record value for DNS verification
verified_at	string?	When the domain was verified (null if pending)
mx_configured	boolean	Whether MX records are correctly configured
created_at	string	When the domain was added

---

Add a Custom Domain

POST /pro/api/domains

Request

curl -X POST https://api.mail.cx/pro/api/domains \
  -H "Authorization: Bearer tm_pro_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"domain":"yourdomain.com"}'

Response 201

{
  "id": "d1e2f3a4-b5c6-7890-def1-234567890abc",
  "domain": "yourdomain.com",
  "verify_token": "mailcx-verify-abc123",
  "dns_records": [
    {
      "type": "TXT",
      "host": "yourdomain.com",
      "value": "mailcx-verify-abc123"
    },
    {
      "type": "MX",
      "host": "yourdomain.com",
      "value": "mx.mail.cx",
      "priority": 10
    }
  ]
}

DNS Setup

After adding a domain, configure these DNS records:

Type	Host	Value	Priority
TXT	yourdomain.com	mailcx-verify-abc123	—
MX	yourdomain.com	mx.mail.cx	10

TIP

DNS changes can take up to 48 hours to propagate. In most cases it takes less than 10 minutes.

Errors

Status	Error Code	Description
400	invalid_domain	Invalid domain name
403	domain_limit_reached	Domain limit reached
409	domain_already_exists	Domain already registered

---

Verify Domain

POST /pro/api/domains/{id}/verify

Check if DNS records are correctly configured. Call this after setting up DNS.

Request

curl -X POST https://api.mail.cx/pro/api/domains/d1e2f3a4-.../verify \
  -H "Authorization: Bearer tm_pro_xxxxxxxxxxxx"

Response 200 — Verified

{
  "verify_status": "verified",
  "txt_record": true,
  "mx_record": true
}

Response 200 — Pending

{
  "verify_status": "pending",
  "txt_record": true,
  "mx_record": false,
  "dns_records": [
    {
      "type": "MX",
      "host": "yourdomain.com",
      "value": "mx.mail.cx",
      "priority": 10
    }
  ]
}

The dns_records array only includes records that are still missing or incorrect.

Errors

Status	Error Code	Description
404	not_found	Domain not found
410	domain_expired	Verification period expired, re-add the domain

---

Delete a Custom Domain

DELETE /pro/api/domains/{id}

Removes the custom domain. Existing mailboxes on this domain will stop receiving emails.

Request

curl -X DELETE https://api.mail.cx/pro/api/domains/d1e2f3a4-... \
  -H "Authorization: Bearer tm_pro_xxxxxxxxxxxx"

Response 204

No content.