Domains
Your sending domains: settings, health, tracking DNS and nameserver checks.
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.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
domainId | path | integer (int64) | required | The domain's id. |
Headers
The endpoints on this page take these headers. Each endpoint's curl shows the ones it sends.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Ken-Version | header | string, one of: 2026-11-02, 1.1 | optional | The 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-Id | header | integer (int64) | optional | The 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
/v1/domainsdomains.list- Permission
- Delivery view
- Rate limit
- 12,000 requests a minute per API key
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:limitis out of range, orcursordid not come from this list.
Requires Delivery view.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
cursor | query | string | optional | The nextCursor from the previous page. Omit it for the first page. |
limit | query | integer (int32) | optional | Domains per page, from 1 to 200. Default 50. |
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
/v1/domains/{domainId}domains.get- Permission
- Delivery view
- Rate limit
- 12,000 requests a minute per API key
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.
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
/v1/domains/{domainId}domains.update- Permission
- Delivery edit
- Rate limit
- 4,800 requests a minute per API key
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 thebillingpermission.websiteMode:redirectorpage.redirectkeeps sending visitors to the forwarding URL;pageasks 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 changesautoRenewand you do not have thebillingpermission. Nothing is written.404 not_found: the workspace has no domain with this id, or atagIdsentry is not a tag of this workspace. Nothing is written.
Requires Delivery edit.
Request body
application/json, optional: object.
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
/v1/domains/{domainId}domains.delete- Permission
- Delivery edit
- Rate limit
- 4,800 requests a minute per API key
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.
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
HTTP/1.1 204 No ContentUpdate many domains
/v1/domains/bulk-updatedomains.bulk-update- Permission
- Delivery edit
- Rate limit
- 480 requests a minute per API key
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:idsis 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 changesautoRenewand you do not have thebillingpermission. Nothing is written.404 not_found: atagIdsentry is not a tag of this workspace. Nothing is written.
Requires Delivery edit.
Request body
application/json, optional: object.
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
/v1/domains/{domainId}/healthdomains.get-health- Permission
- Delivery view
- Rate limit
- 12,000 requests a minute per API key
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.
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
/v1/domains/healthdomains.list-health- Permission
- Delivery view
- Rate limit
- 12,000 requests a minute per API key
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:domainIdsis missing, has a value that is not a positive whole number, or has more than 200 ids.
Requires Delivery view.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
domainIds | query | string | optional | The domains to read: 1 to 200 domain ids, comma-separated. |
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
/v1/domains/{domainId}/dnsdomains.get-dns- Permission
- Delivery view
- Rate limit
- 12,000 requests a minute per API key
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.
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
/v1/domains/{domainId}/verify-dnsdomains.verify-dns- Permission
- Delivery edit
- Rate limit
- 10 requests a minute per API key
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, andlastErrorkeeps it), click tracking is off for the domain, or the workspace has no domain with this id.
Requires Delivery edit.
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
/v1/domains/{domainId}/check-nameserversdomains.check-nameservers- Permission
- Delivery edit
- Rate limit
- 10 requests a minute per API key
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
domainId | path | integer (int64) | required | The domain's id. It must be a domain you imported. |
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.
More in Deliverability:Domain health checksPlacement testsDelivery settingsTracking linksOutbound domain pagesInfrastructure findingsDeliverability rulesAll resources