Domains

Domains represent the email-sending identities for your organisation. Before you can send emails from an address, you must add and verify the domain in Kraiter. Verification involves adding DNS records (DKIM, SPF, DMARC) to prove ownership.

Add domain

POST /api/domains

Adds a new domain to your organisation. After adding, you must configure the DNS records returned in the response and wait for verification.

Request body

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

Response

Returns the domain with its DNS records for verification.

{
  "id": "dom_01H9...",
  "domain": "notifications.example.com",
  "status": "pending",
  "sendingEnabled": false,
  "dnsRecords": [
    {
      "type": "CNAME",
      "name": "abcdef._domainkey.notifications.example.com",
      "value": "abcdef.dkim.amazonses.com",
      "purpose": "DKIM"
    },
    {
      "type": "CNAME",
      "name": "ghijkl._domainkey.notifications.example.com",
      "value": "ghijkl.dkim.amazonses.com",
      "purpose": "DKIM"
    },
    {
      "type": "CNAME",
      "name": "mnopqr._domainkey.notifications.example.com",
      "value": "mnopqr.dkim.amazonses.com",
      "purpose": "DKIM"
    }
  ],
  "createdAt": "2025-09-15T10:00:00.000Z",
  "updatedAt": "2025-09-15T10:00:00.000Z"
}

Errors

Code	Description
`VALIDATION_ERROR`	Invalid domain format.
`CONFLICT`	This domain has already been added.

Examples

curl -X POST https://api.kraiter.com/api/domains \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "domain": "notifications.example.com" }'

const domain = await kraiter.domains.create({
  domain: "notifications.example.com",
});
// Configure the DNS records from domain.dnsRecords

List domains

GET /api/domains

Returns all domains for your organisation.

Response

{
  "data": [
    {
      "id": "dom_01H9...",
      "domain": "notifications.example.com",
      "status": "verified",
      "sendingEnabled": true,
      "createdAt": "2025-09-15T10:00:00.000Z"
    }
  ],
  "nextCursor": null
}

Domain statuses

Status	Description
`pending`	DNS records have not been verified yet.
`verified`	DNS records are confirmed. The domain is ready for sending.
`failed`	Verification failed. Check your DNS records.

Examples

curl https://api.kraiter.com/api/domains \
  -H "Authorization: Bearer YOUR_API_KEY"

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

Get domain

GET /api/domains/:id

Returns a single domain including its DNS records and current verification status.

Path parameters

Parameter	Type	Description
`id`	string	The domain ID.

Response

Returns the full domain object including dnsRecords.

Errors

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

Examples

curl https://api.kraiter.com/api/domains/dom_01H9... \
  -H "Authorization: Bearer YOUR_API_KEY"

const domain = await kraiter.domains.get("dom_01H9...");
console.log(domain.dnsRecords);
console.log(domain.status); // "pending" | "verified" | "failed"

Update domain

PATCH /api/domains/:id

Updates domain settings. Currently supports enabling or disabling sending for a verified domain.

Path parameters

Parameter	Type	Description
`id`	string	The domain ID.

Request body

Field	Type	Required	Description
`sendingEnabled`	boolean	Yes	Whether to enable or disable sending from this domain.

Response

Returns the updated domain.

Errors

Code	Description
`NOT_FOUND`	No domain with this ID exists.
`UNPROCESSABLE_ENTITY`	Cannot enable sending for an unverified domain.

Examples

curl -X PATCH https://api.kraiter.com/api/domains/dom_01H9... \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "sendingEnabled": true }'

const domain = await kraiter.domains.update("dom_01H9...", {
  sendingEnabled: true,
});

Remove domain

DELETE /api/domains/:id

Removes a domain from your organisation. You will no longer be able to send emails from addresses on this domain. Active sequences using this domain will fail on their next send.

Path parameters

Parameter	Type	Description
`id`	string	The domain ID.

Response

Returns 204 No Content on success.

Errors

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

Examples

curl -X DELETE https://api.kraiter.com/api/domains/dom_01H9... \
  -H "Authorization: Bearer YOUR_API_KEY"

await kraiter.domains.delete("dom_01H9...");

Verification process

After adding a domain, follow these steps:

Retrieve the DNS records from the Add domain or Get domain response.
Add each DNS record to your domain's DNS configuration (via your registrar or DNS provider).
Wait for DNS propagation (typically 5-60 minutes, but can take up to 72 hours).
Kraiter checks DNS records periodically. Once verified, the domain status changes to verified.
Enable sending with the Update domain endpoint.

You can check the current status at any time by fetching the domain with GET /api/domains/:id.

Domains

On this page