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 name, its verification status, and the DNS records to configure. Domains are identified by the domain name itself — there is no separate id.

{
  "domain": "notifications.example.com",
  "status": "pending",
  "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": "TXT",
      "name": "_amazonses.notifications.example.com",
      "value": "pmBGN/7MjnfhTKUZ06Enqq1PeGUaOkw8lGhcfwefcHU=",
      "purpose": "Domain verification"
    }
  ]
}

Each DNS record has type (CNAME or TXT), name, value, and purpose (DKIM or Domain verification).

Errors

Code	Description
`VALIDATION_ERROR`	Invalid domain format, or the 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

{
  "items": [
    {
      "domain": "notifications.example.com",
      "status": "verified",
      "sendingEnabled": true,
      "healthStatus": "healthy",
      "dkimTokens": ["abcdef", "ghijkl"],
      "verifiedAt": "2025-09-15T10:05:00.000Z",
      "createdAt": "2025-09-15T10:00:00.000Z",
      "lastCheckedAt": "2025-09-15T10:05:00.000Z"
    }
  ],
  "nextCursor": null
}

Domain statuses

Status	Description
`pending`	Domain added; DNS records not yet created or detected.
`verifying`	DNS records created; verification is in progress.
`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/:domain

Returns a single domain including its DNS records and current verification status. The path parameter is the domain name.

Path parameters

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

Response

Returns the full domain object including dnsRecords.

Errors

Code	Description
`DOMAIN_NOT_FOUND`	No domain with this name exists.

Examples

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

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

Update domain

PATCH /api/domains/:domain

Updates domain settings. Currently supports enabling or disabling sending.

Path parameters

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

Request body

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

Response

Returns the updated domain object.

Errors

Code	Description
`DOMAIN_NOT_FOUND`	No domain with this name exists.
`VALIDATION_ERROR`	No fields were provided to update.

Examples

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

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

Remove domain

DELETE /api/domains/:domain

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
`domain`	string	The domain name (e.g. `notifications.example.com`).

Response

Returns 204 No Content on success.

Errors

Code	Description
`DOMAIN_NOT_FOUND`	No domain with this name exists.

Examples

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

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

Verify domain

POST /api/domains/:domain/verify

Checks the domain's verification status against SES and updates the stored record. Call this after configuring your DNS records to move the domain from pending/verifying to verified without waiting for the next background check.

Response

Returns the updated domain object plus its dnsRecords and a human-readable message.

{
  "domain": "notifications.example.com",
  "status": "verified",
  "sendingEnabled": true,
  "healthStatus": "healthy",
  "dnsRecords": [],
  "message": "Domain is verified and ready for sending"
}

Errors

Code	Description
`DOMAIN_NOT_FOUND`	No domain with this name exists.

Examples

curl -X POST https://api.kraiter.com/api/domains/notifications.example.com/verify \
  -H "Authorization: Bearer YOUR_API_KEY"

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 re-check status on demand by calling POST /api/domains/:domain/verify, which queries SES and updates the stored status. You can also fetch the domain at any time with GET /api/domains/:domain.

Domains

On this page