Domains

The kraiter.domains namespace provides methods for registering sending domains and verifying their DNS configuration. You must verify at least one domain before you can send emails. Domains are identified by their name — there is no separate ID.

create

Registers a new sending domain. After creating a domain, you will need to add DNS records and then call verify to complete the setup.

const domain = await kraiter.domains.create({ domain: 'notifications.example.com' });

console.log(domain.domain);
console.log(domain.status); // "pending"

// The domain object includes the DNS records you need to add
for (const record of domain.dnsRecords) {
  console.log(record.type, record.name, record.value, record.purpose);
}

Parameters

Parameter	Type	Required	Description
`domain`	`string`	Yes	The domain name to register (e.g. `notifications.example.com`), passed as `{ domain }`.

Returns

Promise<Domain> — the newly created domain object, including DNS records to configure.

Domain object

Field	Type	Description
`domain`	`string`	The domain name (also its identifier).
`status`	`string`	Verification status: `"pending"`, `"verifying"`, `"verified"`, or `"failed"`.
`sendingEnabled`	`boolean`	Whether sending from this domain is enabled.
`healthStatus`	`string`	Domain health: `"healthy"`, `"degraded"`, or `"failing"`.
`dnsRecords`	`DnsRecord[]`	The DNS records that must be added to your domain's DNS configuration.
`createdAt`	`string`	ISO 8601 timestamp of when the domain was registered.
`lastCheckedAt`	`string`	ISO 8601 timestamp of the last verification check.
`verifiedAt`	`string`	ISO 8601 timestamp of when the domain was verified, when applicable.

DnsRecord object

Field	Type	Description
`type`	`string`	The DNS record type: `"TXT"`, `"CNAME"`, or `"MX"`.
`name`	`string`	The record name to add to your DNS.
`value`	`string`	The record value.
`purpose`	`string`	What the record is for: `"verification"`, `"dkim"`, `"spf"`, or `"dmarc"`.

Errors

Code	When
`CONFLICT`	This domain is already registered.
`VALIDATION_ERROR`	The domain name is invalid.

get

Retrieves a domain by name. Returns null if not found.

const domain = await kraiter.domains.get('notifications.example.com');

if (domain) {
  console.log(domain.domain, domain.status);
}

Parameters

Parameter	Type	Required	Description
`domain`	`string`	Yes	The domain name.

Returns

Promise<Domain | null> — the domain object, or null if not found.

list

Lists registered domains with cursor-based pagination. Optionally filter by status.

const page = await kraiter.domains.list({ status: 'verified' });

for (const domain of page.items) {
  console.log(domain.domain, domain.status);
}

Parameters

Parameter	Type	Required	Description
`status`	`string`	No	Filter by status (`"pending"`, `"verifying"`, `"verified"`, `"failed"`).
`limit`	`number`	No	Maximum items per page.
`cursor`	`string`	No	Pagination cursor.

Returns

Promise<{ items: Domain[]; nextCursor?: string }> — a page of domain objects.

update

Updates a domain's settings — currently, whether sending from it is enabled.

const domain = await kraiter.domains.update('notifications.example.com', {
  sendingEnabled: false,
});

Parameters

Parameter	Type	Required	Description
`domain`	`string`	Yes	The domain name.
`sendingEnabled`	`boolean`	No	Whether sending from this domain is enabled.

Returns

Promise<Domain> — the updated domain object.

Errors

Code	When
`NOT_FOUND`	No domain exists with this name.

verify

Triggers a DNS verification check for a domain. Call this after you have added the required DNS records.

const result = await kraiter.domains.verify('notifications.example.com');

if (result.verified) {
  console.log('Domain verified — you can now send emails');
} else {
  console.log('Verification failed for records:', result.failedRecords);
}

Parameters

Parameter	Type	Required	Description
`domain`	`string`	Yes	The domain name to verify.

Returns

Promise<VerifyDomainResult> — an object with verified (boolean) and an optional failedRecords array naming the records that did not check out.

Error handling example

import { MailerError } from '@kraiter/sdk';

try {
  const result = await kraiter.domains.verify('notifications.example.com');

  if (!result.verified) {
    console.warn('DNS records not yet propagated — try again in a few minutes');
  }
} catch (error) {
  if (error instanceof MailerError && error.code === 'NOT_FOUND') {
    console.error('Domain not found — register it first with domains.create()');
  } else {
    throw error;
  }
}

delete

Removes a registered domain. You will no longer be able to send emails from this domain.

await kraiter.domains.delete('notifications.example.com');

Parameters

Parameter	Type	Required	Description
`domain`	`string`	Yes	The domain name to delete.

Returns

Promise<void>

Errors

Code	When
`NOT_FOUND`	No domain exists with this name.

DNS propagation

DNS changes can take up to 48 hours to propagate, though most providers complete within a few minutes. If verify reports verified: false, wait and try again. The Kraiter dashboard also provides a real-time view of your domain's DNS status.

Domains

On this page