MX API Domains

Domain lifecycle

Domains are created with a pending status. DNS verification updates the status automatically.

All endpoints require the x-api-key header and a user_id input.

POST

/v2/domain

Create domain

Creates a managed domain, seeds DNS records (MX, SPF, DMARC, DKIM), and returns full domain details.

Request

Body

{
  "domain": "customer.com",
  "user_id": "user_123",
  "organization_id": "org_456"
}

curl -X POST "http://127.0.0.1:3000/v2/domain" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"customer.com","user_id":"user_123","organization_id":"org_456"}'

Response

{
  "message": "Domain created",
  "domain": {
    "domain": { "domain": "customer.com", "status": "pending" },
    "dns": [{ "record_type": "MX", "host": "@", "expected_value": "mx.example.com" }],
    "route": { "domain": "customer.com", "forward_mode": "store" },
    "mx": { "host": "mx.example.com", "priority": 10 }
  }
}

GET

/v2/domains/:domain/info

Get domain

Fetch a single managed domain with DNS and routing details.

Request

Path params: domain

Query: user_id

curl -X GET "http://127.0.0.1:3000/v2/domains/customer.com/info?user_id=user_123" \
  -H "x-api-key: YOUR_API_KEY"

Response

{
  "domain": { "domain": "customer.com", "status": "active" },
  "dns": [{ "record_type": "MX", "host": "@", "expected_value": "mx.example.com" }],
  "route": { "domain": "customer.com", "forward_mode": "store" },
  "mx": { "host": "mx.example.com", "priority": 10 }
}

POST

/v2/domains/delete

Delete domain

Deletes a managed domain and related DNS and route records.

Request

{
  "domain": "customer.com",
  "user_id": "user_123"
}

curl -X POST "http://127.0.0.1:3000/v2/domains/delete" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"customer.com","user_id":"user_123"}'

Response

{ "ok": true, "deleted": "customer.com" }

PUT

/v2/domains/:domain/route

Routing

Updates how inbound mail is handled for a domain.

Request

Path params: domain

{
  "user_id": "user_123",
  "forward_mode": "webhook_then_store",
  "webhook_url": "https://example.com/hook",
  "webhook_secret": "optional-secret",
  "forward_to_email": "inbox@customer.com"
}

curl -X PUT "http://127.0.0.1:3000/v2/domains/customer.com/route" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user_id":"user_123","forward_mode":"webhook_then_store","webhook_url":"https://example.com/hook"}'

Required: webhook_url for webhook modes, forward_to_email for forward_email.

Response

{
  "domain": { "domain": "customer.com", "status": "active" },
  "dns": [],
  "route": { "domain": "customer.com", "forward_mode": "webhook_then_store" },
  "mx": { "host": "mx.example.com", "priority": 10 }
}

GET

/v2/domains/:domain/dns

DNS status

Returns DNS requirements and verification status for a domain.

Request

Path params: domain

Query: user_id

curl -X GET "http://127.0.0.1:3000/v2/domains/customer.com/dns?user_id=user_123" \
  -H "x-api-key: YOUR_API_KEY"

Response

{
  "domain": { "domain": "customer.com", "status": "pending" },
  "dns": [{
    "record_type": "TXT",
    "host": "_dmarc",
    "expected_value": "v=DMARC1; p=none; ..."
  }]
}

POST

/v2/domains/:domain/dns/mark

DNS override

Manual override for DNS record status (admin/testing use).

Request

Path params: domain

{
  "user_id": "user_123",
  "id": 123,
  "status": "verified",
  "observed_value": "v=spf1 mx ~all"
}

curl -X POST "http://127.0.0.1:3000/v2/domains/customer.com/dns/mark" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user_id":"user_123","id":123,"status":"verified"}'

Allowed status: pending, verified, failed, disabled.

Response

{
  "domain": { "domain": "customer.com", "status": "active" },
  "dns": [],
  "route": { "domain": "customer.com", "forward_mode": "store" },
  "mx": { "host": "mx.example.com", "priority": 10 }
}