Create a domain

POST

domains

import { createClient } from "@norbelys/sdk";

const norbelys = createClient({ apiKey: process.env.NORBELYS_API_KEY });

const { data, error } = await norbelys.domains.create({ domain: "notify.acme.com" });
if (error) {
  throw new Error(error.error.message);
}
console.log(data);

{
  "age": {
    "ageDays": 412,
    "sendingAgeDays": 90,
    "source": "rdap",
    "checkedAt": "<unknown>",
    "firstHealthyAt": "<unknown>",
    "firstSeenSendingAt": "<unknown>",
    "registeredAt": "<unknown>"
  },
  "capability": "sending",
  "domain": "notify.acme.com",
  "id": "dom_h2wq8vzr1k4m9x3c5b7n0jfe",
  "monitoring": {
    "collectionStatus": "collecting",
    "dmarcPolicy": "quarantine",
    "kind": "external",
    "passRate7d": 0.97,
    "recordToPublish": {
      "host": "_dmarc.acme.com",
      "type": "TXT",
      "value": "v=DMARC1; p=none; rua=mailto:[email protected]"
    },
    "sendingDomainId": "dom_h2wq8vzr1k4m9x3c5b7n0jfe",
    "lastReportAt": "2026-06-01T12:30:00.000Z"
  },
  "senderCount": 3,
  "sending": {
    "capacity": {
      "campaignUsed": 42,
      "domainRemaining": 158,
      "limitingReason": "domain_daily_limit",
      "mailboxCapacity": 200,
      "warmupReserved": 20,
      "nextResetAt": "<unknown>"
    },
    "defaultTrackingDomainId": "dom_h2wq8vzr1k4m9x3c5b7n0jfe",
    "health": {
      "reasons": [
        "<string>"
      ],
      "recommendedAction": "reduce_first_touches",
      "state": "healthy",
      "updatedAt": "<unknown>"
    },
    "policy": {
      "allowPauseAll": true,
      "allowPauseFirstTouches": true,
      "autopilotMax": 500,
      "autopilotMin": 50,
      "configuredDailyCap": 200,
      "effectiveDailyCap": 180,
      "maxDailyGrowthPercent": 20,
      "mode": "autopilot",
      "recommendedDailyCap": 220,
      "timezone": "America/New_York"
    },
    "senderCount": 3
  },
  "tracking": {
    "assignedSendingDomainIds": [
      "<string>"
    ],
    "cloudflareHostnameId": "<string>",
    "desiredState": "active",
    "dnsStatus": "valid",
    "domainConnectSupported": true,
    "domainConnectUrl": "<string>",
    "httpStatus": "valid",
    "isOrganizationDefault": true,
    "label": "Marketing links",
    "provider": "cloudflare",
    "providerDisplayName": "Cloudflare",
    "providerUrl": "<string>",
    "record": {
      "host": "track.acme.com",
      "type": "CNAME",
      "value": "custom-track.generate-mcp.com"
    },
    "setupMode": "manual",
    "status": "active",
    "tlsStatus": "valid",
    "lastCheckedAt": "<unknown>"
  },
  "version": 2,
  "createdAt": "2026-05-20T09:00:00.000Z",
  "object": "domain"
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

Authorizations

Authorization

string

header

required

Org-scoped Norbelys API key. Create one in Settings → API keys and send it as Authorization: Bearer ak_….

Headers

Idempotency-Key

string

Opt-in idempotency for a safely retried write: reuse the same key to replay the original result for 24h instead of re-executing. Recommended on every POST.

Maximum string length: 255

Body

application/json

domain

string

required

The bare DNS name.

Pattern: ^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$

Example:

"notify.acme.com"

capability

enum<string>

default:sending

What the domain is for: sending, monitoring, or tracking. Defaults to sending.

Available options:

sending,

monitoring,

tracking

Example:

"monitoring"

monitoring

DomainMonitoringParams · object

Monitoring options (capability "monitoring" only).

Show child attributes

tracking

DomainTrackingParams · object

Tracking options (capability "tracking" only).

Show child attributes

Response

age

DomainAge · object | null

required

Registration and observed-sending age for a sending domain.

Show child attributes

capability

enum<string>

required

What the domain is for: sending, monitoring, or tracking.

Available options:

sending,

monitoring,

tracking

Example:

"sending"

domain

string

required

The bare DNS name.

Example:

"notify.acme.com"

string

required

The domain id.

Example:

"dom_h2wq8vzr1k4m9x3c5b7n0jfe"

monitoring

DomainMonitoring · object | null

required

DMARC-monitoring rollup + collection status; null on a sending row.

Show child attributes

senderCount

integer | null

required

Mailboxes on this sending domain attached to the filtered campaign — present only when listing with ?programId.

Required range: x >= 0

Example:

3

sending

DomainSending · object | null

required

Sending policy, capacity, and health; null for other capabilities.

Show child attributes

tracking

DomainTracking · object | null

required

Custom tracking hostname state; null for other capabilities.

Show child attributes

version

integer

required

Optimistic concurrency version.

Required range: x >= 1

createdAt

any

Creation instant (RFC 3339).

Example:

"2026-05-20T09:00:00.000Z"

object

any

default:domain

Always "domain" — the resource discriminator.

import { createClient } from "@norbelys/sdk";

const norbelys = createClient({ apiKey: process.env.NORBELYS_API_KEY });

const { data, error } = await norbelys.domains.create({ domain: "notify.acme.com" });
if (error) {
  throw new Error(error.error.message);
}
console.log(data);

{
  "age": {
    "ageDays": 412,
    "sendingAgeDays": 90,
    "source": "rdap",
    "checkedAt": "<unknown>",
    "firstHealthyAt": "<unknown>",
    "firstSeenSendingAt": "<unknown>",
    "registeredAt": "<unknown>"
  },
  "capability": "sending",
  "domain": "notify.acme.com",
  "id": "dom_h2wq8vzr1k4m9x3c5b7n0jfe",
  "monitoring": {
    "collectionStatus": "collecting",
    "dmarcPolicy": "quarantine",
    "kind": "external",
    "passRate7d": 0.97,
    "recordToPublish": {
      "host": "_dmarc.acme.com",
      "type": "TXT",
      "value": "v=DMARC1; p=none; rua=mailto:[email protected]"
    },
    "sendingDomainId": "dom_h2wq8vzr1k4m9x3c5b7n0jfe",
    "lastReportAt": "2026-06-01T12:30:00.000Z"
  },
  "senderCount": 3,
  "sending": {
    "capacity": {
      "campaignUsed": 42,
      "domainRemaining": 158,
      "limitingReason": "domain_daily_limit",
      "mailboxCapacity": 200,
      "warmupReserved": 20,
      "nextResetAt": "<unknown>"
    },
    "defaultTrackingDomainId": "dom_h2wq8vzr1k4m9x3c5b7n0jfe",
    "health": {
      "reasons": [
        "<string>"
      ],
      "recommendedAction": "reduce_first_touches",
      "state": "healthy",
      "updatedAt": "<unknown>"
    },
    "policy": {
      "allowPauseAll": true,
      "allowPauseFirstTouches": true,
      "autopilotMax": 500,
      "autopilotMin": 50,
      "configuredDailyCap": 200,
      "effectiveDailyCap": 180,
      "maxDailyGrowthPercent": 20,
      "mode": "autopilot",
      "recommendedDailyCap": 220,
      "timezone": "America/New_York"
    },
    "senderCount": 3
  },
  "tracking": {
    "assignedSendingDomainIds": [
      "<string>"
    ],
    "cloudflareHostnameId": "<string>",
    "desiredState": "active",
    "dnsStatus": "valid",
    "domainConnectSupported": true,
    "domainConnectUrl": "<string>",
    "httpStatus": "valid",
    "isOrganizationDefault": true,
    "label": "Marketing links",
    "provider": "cloudflare",
    "providerDisplayName": "Cloudflare",
    "providerUrl": "<string>",
    "record": {
      "host": "track.acme.com",
      "type": "CNAME",
      "value": "custom-track.generate-mcp.com"
    },
    "setupMode": "manual",
    "status": "active",
    "tlsStatus": "valid",
    "lastCheckedAt": "<unknown>"
  },
  "version": 2,
  "createdAt": "2026-05-20T09:00:00.000Z",
  "object": "domain"
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

Analytics

Domains

Fields

Files

Groups

Integrations

Messages

Organization

People

Programs

Segments

Senders

Suppressions

Verify

Authorizations

Headers

Body

Response