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.

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('notifications.example.com');

console.log(domain.id);
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);
}

Parameters

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

Returns

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

Domain object

Field	Type	Description
`id`	`string`	Unique domain ID.
`domain`	`string`	The domain name.
`status`	`string`	Current verification status: `"pending"`, `"verified"`, or `"failed"`.
`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.
`verifiedAt`	`string \| null`	ISO 8601 timestamp of when the domain was verified, or `null`.

DnsRecord object

Field	Type	Description
`type`	`string`	The DNS record type (e.g. `CNAME`, `TXT`).
`name`	`string`	The record name to add to your DNS.
`value`	`string`	The record value.

Errors

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

get

Retrieves a domain by ID.

const domain = await kraiter.domains.get('dom_abc123');
console.log(domain.domain, domain.status);

Parameters

Parameter	Type	Required	Description
`id`	`string`	Yes	The domain ID.

Errors

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

list

Lists all registered domains. Unlike other list methods, this returns a Promise that resolves to an array rather than an async iterator, since the number of domains per tenant is typically small.

const domains = await kraiter.domains.list();

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

Returns

Promise<Domain[]> — an array of domain objects.

Triggers a DNS verification check for a domain. Call this after you have added the required DNS records. If verification succeeds, the domain status changes to "verified" and you can start sending from it.

const domain = await kraiter.domains.verify('dom_abc123');

if (domain.status === 'verified') {
  console.log('Domain verified — you can now send emails');
} else {
  console.log('Verification failed — check your DNS records');
  for (const record of domain.dnsRecords) {
    console.log(record.type, record.name, record.value);
  }
}

Parameters

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

Returns

Promise<Domain> — the domain object with an updated status.

Errors

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

Error handling example

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

try {
  const domain = await kraiter.domains.verify('dom_abc123');

  if (domain.status !== 'verified') {
    console.warn('DNS records not yet propagated — try again in a few minutes');
  }
} catch (error) {
  if (error instanceof KraiterError && 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('dom_abc123');

Parameters

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

Returns

Promise<void>

Errors

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

DNS propagation

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

Domains

On this page