Add a Domain

Register and verify a custom sending domain.

Register a custom domain and verify its DNS configuration to start sending authenticated emails.

Scope: domains:manage

Rate limit: 1,000/hr

Step 1: Register the domain

POST /api/v1/domains

Field	Type	Required	Description
domain	string	Yes	The domain or subdomain to register

curl -X POST https://api.platformxe.com/api/v1/domains \
  -H "Content-Type: application/json" \
  -H "x-api-key: pxk_live_your_api_key_here" \
  -d '{
    "domain": "mail.yourcompany.com"
  }'

const domain = await px.registerDomain({
  domain: 'mail.yourcompany.com',
});

Response

{
  "success": true,
  "data": {
    "id": "dom_abc123",
    "domain": "mail.yourcompany.com",
    "status": "pending",
    "dnsRecords": [
      { "type": "TXT", "name": "mail.yourcompany.com", "value": "v=spf1 include:_spf.platformxe.com ~all" },
      { "type": "TXT", "name": "pxe._domainkey.mail.yourcompany.com", "value": "v=DKIM1; k=rsa; p=MIGfMA0G..." },
      { "type": "TXT", "name": "_dmarc.mail.yourcompany.com", "value": "v=DMARC1; p=quarantine; rua=mailto:dmarc@platformxe.com" }
    ]
  }
}

Step 2: Configure DNS

Add each DNS record to your domain's DNS provider. The exact steps vary by provider — consult your DNS provider's documentation for adding TXT records.

Step 3: Verify the domain

POST /api/v1/domains/:id/verify

After configuring DNS records, trigger verification:

curl -X POST https://api.platformxe.com/api/v1/domains/dom_abc123/verify \
  -H "x-api-key: pxk_live_your_api_key_here"

const result = await px.verifyDomain('dom_abc123');
console.log(result.data.status); // "verified" or "pending"

Response

{
  "success": true,
  "data": {
    "id": "dom_abc123",
    "domain": "mail.yourcompany.com",
    "status": "verified",
    "verifiedAt": "2026-04-05T15:00:00.000Z"
  }
}

Error responses

Code	Description
BAD_REQUEST	Invalid domain format
CONFLICT	Domain already registered
VERIFICATION_FAILED	DNS records not found or misconfigured
FORBIDDEN	API key missing domains:manage scope