Skip to Content
Deliverability

Domains

Your sending domains: settings, health, tracking DNS and nameserver checks.

Deliverability10 endpointsKen-Version: 2026-11-02AuthenticationWorkspacesErrors
MarkdownOpenAPI

Path parameters

The endpoints whose path names one of these take it as described here. An endpoint's own table lists a path parameter only when it describes it differently.

NameInTypeRequiredDescription
domainIdpathinteger (int64)requiredThe domain's id.

Headers

The endpoints on this page take these headers. Each endpoint's curl shows the ones it sends.

NameInTypeRequiredDescription
Ken-Versionheaderstring, one of: 2026-11-02, 1.1optionalThe API version, a date in YYYY-MM-DD form. 1.1 is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and 404 where the path exists only in this version. A date that is not a version answers 400 unsupported_version; any other value that is not a version is treated as legacy.
X-Ken-Workspace-Idheaderinteger (int64)optionalThe id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers 400 workspace_required. A workspace you are not a member of answers 404 not_found.

List domains

GET/v1/domainsdomains.list
Permission
Delivery view
Rate limit
12,000 requests a minute per API key

Try it on developer.ken.so

Returns the workspace's domains, one page at a time. Each item has the same shape as GET /v1/domains/{domainId}.

limit is from 1 to 200 and defaults to 50. To get the next page, send the nextCursor of the previous page as cursor.

Errors:

  • 400 validation_failed: limit is out of range, or cursor did not come from this list.

Requires Delivery view.

Parameters

NameInTypeRequiredDescription
cursorquerystringoptionalThe nextCursor from the previous page. Omit it for the first page.
limitqueryinteger (int32)optionalDomains per page, from 1 to 200. Default 50.
Request
curl -X GET "https://api.ken.so/v1/domains?limit=50" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"

Response 200

data is a list of Domain. Each item has these fields. The response also carries pagination.

Show the 33 response fields and an example

The fields and an example are also on this endpoint's Markdown page.

Get a domain

GET/v1/domains/{domainId}domains.get
Permission
Delivery view
Rate limit
12,000 requests a minute per API key

Try it on developer.ken.so

Returns one domain with its status, registration and renewal, click tracking, ramp-up and tags.

For a domain you imported, it also returns nameservers: the two nameservers to set at the domain's registrar (expected), the ones it has now (current) and status (pending, action_required after 24 hours without the change, or active), and registrarInfo: the registrar from public RDAP with the key of its steps (guide). The domain stays at its registrar; Kenso never transfers it. When the nameservers already point at Kenso but setup waits for credits to pay the first month of the domain's mailboxes, nameservers.waitingForCredits is true, with requiredMillicredits and availableMillicredits. The fields mean what they mean on the nameserver check, but this read reports the wait as soon as the nameservers match, which can be before Kenso's DNS zone for the domain is active; the check reports it only once the zone is active.

Errors:

  • 404 not_found: the workspace has no domain with this id.

Requires Delivery view.

Request
curl -X GET "https://api.ken.so/v1/domains/812" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"

Response 200

data is a Domain.

Show the 33 response fields and an example

The fields and an example are also on this endpoint's Markdown page.

Update a domain

PATCH/v1/domains/{domainId}domains.update
Permission
Delivery edit
Rate limit
4,800 requests a minute per API key

Try it on developer.ken.so

Changes one domain's settings. Send only the fields you want to change: a field you leave out keeps its value.

The body fields:

  • clickRateTrackingEnabled: true or false. Turns click tracking through this domain on or off.
  • rampUpDays: a whole number from 0 to 30. Over this many days Kenso raises the daily send limit of the domain's inboxes to their full limit. 0 turns ramp-up off.
  • redirectUrl404: the forwarding URL, where Kenso sends people who open the domain in a browser. A public http or https URL, or null to clear it. Kenso refuses a URL that fails its link reputation check.
  • tagIds: the domain's tags. The list replaces the current tags; an empty list or null removes them all.
  • autoRenew: true or false. Whether Kenso renews the domain's registration before it expires. Only a domain Kenso bought can renew (autoRenewEligible). Changing it also needs the billing permission.
  • websiteMode: redirect or page. redirect keeps sending visitors to the forwarding URL; page asks Kenso to serve the workspace's outbound site page on the domain. Once set, it cannot go back to unset.

Kenso saves the fields one after another and stops at the first field that fails. The error message then names the fields already saved. A body with no fields returns the domain unchanged. Returns the updated domain. Example: { "rampUpDays": 21, "tagIds": [12] }.

Errors:

  • 400 validation_failed: a field has a wrong value, the body has an unknown field, or a change failed.
  • 403 permission_denied: the body changes autoRenew and you do not have the billing permission. Nothing is written.
  • 404 not_found: the workspace has no domain with this id, or a tagIds entry is not a tag of this workspace. Nothing is written.

Requires Delivery edit.

Request body

application/json, optional: object.

Request
curl -X PATCH "https://api.ken.so/v1/domains/812" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{}'

Response 200

data is a Domain.

Show the 33 response fields and an example

The fields and an example are also on this endpoint's Markdown page.

Delete a domain

DELETE/v1/domains/{domainId}domains.delete
Permission
Delivery edit
Rate limit
4,800 requests a minute per API key

Try it on developer.ken.so

Removes the domain from the workspace. Kenso stops serving the redirects and tracked links on the domain. Returns 204 with no body.

Errors:

  • 400 validation_failed: the domain is hosted by your email provider, not by Kenso, which keeps it only to check the mailboxes connected on it.
  • 404 not_found: the workspace has no domain with this id.

Requires Delivery edit.

Request
curl -X DELETE "https://api.ken.so/v1/domains/812" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"

Response 204

Response 204
HTTP/1.1 204 No Content

Update many domains

POST/v1/domains/bulk-updatedomains.bulk-update
Permission
Delivery edit
Rate limit
480 requests a minute per API key

Try it on developer.ken.so

Applies the same changes to up to 1,000 domains in one call, such as turning click tracking on for a group of domains or giving them all the same tags.

The body is a JSON object with ids, a list of 1 to 1,000 domain ids, and at least one field to change. The fields and their rules are the same as on PATCH /v1/domains/{domainId}: clickRateTrackingEnabled, rampUpDays, redirectUrl404, tagIds, autoRenew and websiteMode. Every domain gets the same values. Kenso ignores a repeated id.

Kenso updates each domain on its own, so one failed domain does not stop the others. The response gives updatedCount, the number of domains updated, and one failed entry with the reason for each domain that was not, such as an id that is not a domain of this workspace. Example: { "ids": [4, 9], "rampUpDays": 14 }.

Errors:

  • 400 validation_failed: ids is missing, empty or longer than 1,000, the body has no field to change or an unknown field, or a field has a wrong value.
  • 403 permission_denied: the body changes autoRenew and you do not have the billing permission. Nothing is written.
  • 404 not_found: a tagIds entry is not a tag of this workspace. Nothing is written.

Requires Delivery edit.

Request body

application/json, optional: object.

Request
curl -X POST "https://api.ken.so/v1/domains/bulk-update" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{}'

Response 200

data is a DomainBulkResult.

Show the 2 response fields and an example

The fields and an example are also on this endpoint's Markdown page.

Get a domain's health

GET/v1/domains/{domainId}/healthdomains.get-health
Permission
Delivery view
Rate limit
12,000 requests a minute per API key

Try it on developer.ken.so

Returns the latest health results for one domain: blocklist listings, mail DNS records, bounce rate, the latest placement test, nameservers and the SSL certificate. Use it to find out why a domain's mail lands in spam or bounces.

The blocklist, mail DNS and certificate fields come from the latest health check, dated by checkedAt. Kenso runs a check every day, and you can start one with POST /v1/domain-health-checks. They stay the same until the next check finishes, except blocklistVerdict: it also counts Kenso's own daily blocklist check, and stops counting a health check more than 7 days old. Rates are fractions from 0 to 1.

Errors:

  • 404 not_found: the workspace has no domain with this id.

Requires Delivery view.

Request
curl -X GET "https://api.ken.so/v1/domains/812/health" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"

Response 200

data is a DomainHealth.

Show the 34 response fields and an example

The fields and an example are also on this endpoint's Markdown page.

List the health of many domains

GET/v1/domains/healthdomains.list-health
Permission
Delivery view
Rate limit
12,000 requests a minute per API key

Try it on developer.ken.so

Returns the latest health results for up to 200 domains in one call, such as every domain on a page. Each item is what GET /v1/domains/{domainId}/health returns for that domain, so the fields, their sources and how fresh they are read the same way there.

domainIds is required: 1 to 200 domain ids, comma-separated, such as domainIds=4,9,12. Items come in the order of domainIds, and Kenso ignores a repeated id. An id that is not a domain of this workspace has no item, where the one-domain read answers 404. The list has no further pages: pagination.hasMore is always false.

Errors:

  • 400 validation_failed: domainIds is missing, has a value that is not a positive whole number, or has more than 200 ids.

Requires Delivery view.

Parameters

NameInTypeRequiredDescription
domainIdsquerystringoptionalThe domains to read: 1 to 200 domain ids, comma-separated.
Request
curl -X GET "https://api.ken.so/v1/domains/health" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"

Response 200

data is a list of DomainHealth. Each item has these fields. The response also carries pagination.

Show the 34 response fields and an example

The fields and an example are also on this endpoint's Markdown page.

Get a domain's tracking DNS

GET/v1/domains/{domainId}/dnsdomains.get-dns
Permission
Delivery view
Rate limit
12,000 requests a minute per API key

Try it on developer.ken.so

Returns the click tracking DNS state of one domain: whether its DNS points at Kenso's redirect servers, which click tracking through the domain needs, and its open pixel host. Kenso rechecks the DNS on a schedule. To check it right away, for example after you changed a record, call POST /v1/domains/{domainId}/verify-dns.

Errors:

  • 404 not_found: the workspace has no domain with this id.

Requires Delivery view.

Request
curl -X GET "https://api.ken.so/v1/domains/812/dns" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"

Response 200

data is a DomainDns.

Show the 6 response fields and an example

The fields and an example are also on this endpoint's Markdown page.

Verify a domain's tracking DNS

POST/v1/domains/{domainId}/verify-dnsdomains.verify-dns
Permission
Delivery edit
Rate limit
10 requests a minute per API key

Try it on developer.ken.so

Checks now whether the domain's DNS records point at Kenso's redirect servers, saves the result and returns it in the same shape as GET /v1/domains/{domainId}/dns. Call it after you add or change the records. The domain must have click tracking on (clickRateTrackingEnabled).

Errors:

  • 400 validation_failed: the records do not point at Kenso yet (the message gives the reason, and lastError keeps it), click tracking is off for the domain, or the workspace has no domain with this id.

Requires Delivery edit.

Request
curl -X POST "https://api.ken.so/v1/domains/812/verify-dns" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"

Response 200

data is a DomainDns.

Show the 6 response fields and an example

The fields and an example are also on this endpoint's Markdown page.

Check a domain's nameservers

POST/v1/domains/{domainId}/check-nameserversdomains.check-nameservers
Permission
Delivery edit
Rate limit
10 requests a minute per API key

Try it on developer.ken.so

For a domain you imported, checks whether its nameservers now point at the DNS zone Kenso created for it in Kenso's DNS account, and starts setting the domain up once they do. Call it after you change the nameservers at your registrar. expectedNameservers lists the nameservers to set.

activated turns true once the domain is set up. Until then the response says where it stands: zoneStatus is the zone's state, and waitingForCredits is true when setup waits for credits to pay the first month of the domain's mailboxes. Add credits, then call again.

Errors:

  • 400 validation_failed: Kenso has no DNS zone for the domain.
  • 404 not_found: the workspace has no imported domain with this id.
  • 503 service_unavailable: Kenso could not check the zone. Try again later.

Requires Delivery edit.

Parameters

NameInTypeRequiredDescription
domainIdpathinteger (int64)requiredThe domain's id. It must be a domain you imported.
Request
curl -X POST "https://api.ken.so/v1/domains/812/check-nameservers" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"

Response 200

data is a DomainNameserverCheck.

Show the 9 response fields and an example

The fields and an example are also on this endpoint's Markdown page.


On this page