Domains domains
update and bulk-update take changes (tracking, ramp-up, ...). Several domains: one bulk-update with ids and changes, never update per domain. One domain's id by name: list with q (part of the name).
Call it from an MCP client connected to https://mcp.ken.so/mcp: reads go through domains_read and changes through domains_write. Each takes operation plus that operation's parameters, and your workspace role decides which operations you see.
Each operation with a route calls the Kenso API at https://api.ken.so with Authorization: Bearer <Kenso API key>, Ken-Version: 1.1 and X-Ken-Workspace-Id: <workspace id>. You can call that route directly with the same headers.
Operations: bulk-update, check-nameservers, domain-health-checks-create, sender-name-suggestions-create, create-inbox, create-own-domain, delete, hosting-hostname-delete, delete-own-domain, get, hosting-hostname-get, get-dns, get-health, list, list-health, list-own-domains, hosting-hostname-set, update, hosting-hostname-verify, verify-dns
bulk-update
Write. POST https://api.ken.so/v1/domains/bulk-update
Apply one field update to up to 1,000 domains. Requires Delivery edit access (owners, admins and editors by default). Auto-renew also needs the billing permission (admins by default).
POST /api/v1/domains/bulk-update. Public. Sends Ken-Version 1.1. Masking and catch-all require SuperAdmin. website_mode: page or redirect for every id, the person's answer to "What should people see when they open these domains? A rebuild of your website (recommended) or a redirect to your website?". Ask them, never choose for them. An id outside the workspace is in failed with "Domain was not found.".
check-nameservers
Write. POST https://api.ken.so/v1/domains/{domainId}/check-nameservers
Path: domainId
Check imported-domain nameservers against the Kenso DNS zone. Requires Delivery edit access (owners, admins and editors by default).
POST /api/v1/domains/{domainId}/check-nameservers. Public. Sends Ken-Version 1.1.
Returns status, zoneStatus, activated, expectedNameservers and waitingForCredits
with requiredMillicredits and availableMillicredits, as domains(operation="get", domain_id=...) says.
domain-health-checks-create
Write. POST https://api.ken.so/v1/domain-health-checks
Body (json): domainIds array
Start a domain health check. Returns 202 and a domain_health job. Requires Delivery edit. Omit domain_ids to check every domain in the workspace.
POST /api/v1/domain-health-checks. Public. Sends Ken-Version 1.1.
Poll with GET /api/v1/jobs/{jobId}?type=domain_health.
A completed domain_health job includes domainsListed, including 0. It is
omitted until that count exists. Other job types do not get the field.
domain_ids accepts at most 1000 ids. A check already running is 409 conflict
and includes that job in data. A zero id is rejected before the request.
sender-name-suggestions-create
Write. POST https://api.ken.so/v1/sender-name-suggestions
Body (json): count integer, excludeNames array
Suggest unique sender names for new inboxes. Internal. Requires Delivery edit access. count is 1 to 100.
POST /api/v1/sender-name-suggestions. Internal. Sends Ken-Version 1.1. Names already used by the workspace inboxes are skipped. exclude_names are full names to skip, such as Ada Lovelace. The response is suggestions of firstName and lastName. It omits the workspace id.
create-inbox
Write. POST https://api.ken.so/v1/domains/{domainId}/inboxes
Path: domainId
Body (json): firstName string, lastName string, localPart string, prewarmed boolean
SPENDS CREDITS: buys a real Kenso mailbox on a Kenso-managed domain. Costs 200 credits a month per Google or Outlook inbox, first month now (an Azure domain's inboxes are in its domain price). Confirm the cost with the user before calling. Off (not_found) without the domain_add_inbox flag. Needs Delivery edit + Billing.
POST /api/v1/domains/{domainId}/inboxes. Internal. Sends Ken-Version 1.1.
Buys one Kenso mailbox on the domain and returns 201 with the new inbox
(status warmup or pending_provisioning; it warms up before it sends).
Price a Google or Outlook inbox first: billing operation credit-estimates-create with
kind "infra" and items [{"action": "ken_inbox_monthly", "quantity": 1}]. An Azure
domain's inboxes cost nothing beyond the domain.
Only domains Kenso bought for the workspace (source platform_purchased) qualify; any other
domain is validation_failed with detail code not_ken_managed (connect an inbox instead).
The domain must be active, else detail code domain_not_active.
first_name / last_name default to the domain's most common sender name, else the
workspace owner's. local_part (the address before the @: lowercase letters, digits,
single . - _ separators, at most 64 characters) defaults to the first free of first,
first.last, firstl, f.last, firstlast, then first.last2, first.last3, ..., skipping every
address an inbox holds, deleted inboxes included.
A given local_part that an inbox bought on this domain in the last 24 hours holds returns
200 with that inbox and buys nothing (the retry case). Any other holder is conflict with
detail code local_part_taken, before anything is bought. When that detail has inboxId,
the address already exists as that inbox: do not buy it again.
Too few credits is 402 plan_limit_reached with refusal INSUFFICIENT_CREDITS, or
FREE_CREDITS_NOT_ELIGIBLE when only free or bonus credits would cover it (they can't pay for inboxes).
Another purchase running on the same domain is conflict; retry after a minute.
upstream_timeout (504) means the mailbox may exist: error.details[0] has code
pending_confirmation and allowed[0] = the local part Kenso chose. Do not call again
without that local_part; a retry with it returns or adds that mailbox instead of buying
another. service_unavailable (503) means the provider refused or could not be reached
and no credits were spent.
Prewarmed inboxes are not available on this route.
create-own-domain
Write. POST https://api.ken.so/v1/workspaces/{workspaceId}/own-domains
Path: workspaceId
Body (json): domain string
Add one of the workspace's own domains (workspace settings permission). The URL or domain is normalized; free-mail domains are refused.
POST /api/v1/workspaces/{workspaceId}/own-domains with Ken-Version 1.1.
Internal exposure. The backend requires the workspace settings
permission (the Admin and Editor templates by default).
domain may be a bare domain or a URL: the backend trims, lowercases and
strips http(s)://, a leading www., any path or query, and a trailing
dot. Errors:
- 400 validation_failed: not a domain (details code invalid), a
free-mail domain such as gmail.com (free_mail_domain), or the
workspace already has 20 added domains (limit_reached).
- 409 conflict: the domain is already the Primary or already added.
- 409 invalid_state (details code cold_sending_domain): campaign
inboxes send cold email from the domain, so it is not the company's
own domain.
201 with data {domain, isPrimary false, createdAt}.
delete
Write. DELETE https://api.ken.so/v1/domains/{domainId}
Path: domainId
Delete a domain. Returns 204. Requires Delivery edit.
DELETE /api/v1/domains/{domainId}. Public. Sends Ken-Version 1.1.
hosting-hostname-delete
Write. DELETE https://api.ken.so/v1/hosting/hostname
Query: purpose string
Remove the workspace hosting hostname and detach it from the edge. Empty success means it was removed.
DELETE /api/v1/hosting/hostname. Internal. Sends Ken-Version 1.1. Requires Delivery edit access. The backend returns 204. Routes return 404 not_found unless the workspace has the studio or accounts_send feature on. purpose is studio (default) or booking: booking removes both Scheduler hosts, the current and the previous one, and works even with the scheduler feature off.
delete-own-domain
Write. DELETE https://api.ken.so/v1/workspaces/{workspaceId}/own-domains/{domain}
Path: workspaceId, domain
Remove one of the workspace's own domains, the Primary included. Empty success means the domain was removed. Needs workspace settings.
DELETE /api/v1/workspaces/{workspaceId}/own-domains/{domain} with
Ken-Version 1.1. Internal exposure. The backend requires the workspace
settings permission and returns 204 with an empty body.
Pass the bare domain, for example acme.io. Removing the Primary clears
the workspace's email domain; no other domain takes its place. An
unknown domain is 404. Refusals are 409 invalid_state with a details
code:
- last_domain: it is the workspace's only domain. Add another first.
- hostname_in_use: a Studio or booking hostname sits on the domain.
Remove that hostname first.
get
Read. GET https://api.ken.so/v1/domains/{domainId}
Path: domainId
Return one domain in the current workspace. A missing or cross-workspace id is not_found.
GET /api/v1/domains/{domainId}. Public. Sends Ken-Version 1.1.
Requires Delivery view. Carries isPrimary, rampUp, campaignPixelHost,
replacedBy and health as on list; imported domains add registrarInfo and
nameservers {expected, current, status (pending, action_required, active),
waitingForCredits, requiredMillicredits, availableMillicredits}.
waitingForCredits true: the nameservers already point at Kenso, but setup
waits until the balance pays the first month of the domain's mailboxes.
Only then are requiredMillicredits (that month) and availableMillicredits
(the balance) set; 1 credit = 1,000 millicredits. Once credits are added,
setup continues on the next check (Kenso checks every 15 minutes;
domains(operation="check-nameservers", domain_id=...) checks now).
hosting-hostname-get
Read. GET https://api.ken.so/v1/hosting/hostname
Query: purpose string
Read the workspace hosting hostname (go.acme.com) that serves Studio pages and the open pixel. Includes its status and the DNS record the customer must add. purpose="booking" reads the Scheduler host.
GET /api/v1/hosting/hostname. Public. Sends Ken-Version 1.1. Requires
Delivery view. Every hosting hostname route returns 404 not_found unless the
workspace has the studio or accounts_send feature on (purpose=booking:
scheduler).
purpose is studio (default) or booking. booking reads the workspace's
current Scheduler host on its own domain.
Returns {hostname, subdomain, domain, status, error, dnsRecord,
ownershipRecord, readyAt, lastCheckedAt}. domain is the parent domain (the
hostname after its first label). status is pending, ready, or failed. Only
ready serves links and the pixel. error is null after a success, else one of
hostname_ownership_missing, hostname_cname_missing, certificate_pending,
dns_missing, route_conflict, pixel_unreachable, provider_disabled,
provider_error.
dnsRecord is {type: "CNAME", name, value}: the record the customer adds at
their DNS host (name is the hostname, value is the target). It is null when
Kenso serves the host from its own zone, and then nothing needs publishing.
ownershipRecord is {type: "TXT", name: "_ken-verify.<hostname>", value}: a
Scheduler host on another domain publishes it beside the CNAME to prove the
workspace controls the name. It is set only while error is
hostname_ownership_missing; Kenso creates nothing for the host before that.
get-dns
Read. GET https://api.ken.so/v1/domains/{domainId}/dns
Path: domainId
Return tracking DNS state for one domain. tracking status is verified, dead, or unchecked.
GET /api/v1/domains/{domainId}/dns. Public. Sends Ken-Version 1.1.
Requires Delivery view. open pixel status is pending, verified, disabled, or none.
get-health
Read. GET https://api.ken.so/v1/domains/{domainId}/health
Path: domainId
Return the latest health snapshot for one domain, with its SPF, DKIM, DMARC and MX verdicts. spfStatus, dkimStatus, dmarcStatus and mxStatus are pass, fail or unknown from the last check. blocklistVerdict (listed, clean or unknown) also counts Kenso's own daily blocklist check, and listedSince dates a listing; URIBL grey alone isn't a listing (uriblGreyOnly). Rates are fractions from 0 to 1. A domain outside the workspace is not_found. Full docs: describe_tools(['api_domains_get_health'])
GET /api/v1/domains/{domainId}/health. Public. Sends Ken-Version 1.1.
Requires Delivery view. Includes blacklist, mail DNS, bounce, placement,
nameserver, and certificate state. inboxRate, spamRate, and bounceRate are
fractions. ipAbuseScore is included and omitted when the check has none.
Mail DNS verdicts: spfStatus, dkimStatus, dmarcStatus and mxStatus are
pass, fail or unknown (omitted before the domain's first check). hasSpf,
hasDkim, hasDmarc and hasMx are true only on pass. dkimSelector is the
selector the DKIM check used. isChecked is true once SPF, DKIM and DMARC
are all pass or fail.
Blocklist: blocklistVerdict (listed, clean or unknown) is Kenso's
combined verdict, by the rule its deliverability alerts use to call a
domain blocklisted. It is listed when Kenso's own daily blocklist check
lists the domain, or when the latest health check is no more than 7 days
old and says listed, unless the only zones it names are URIBL grey.
Every other zone counts, URIBL black and red included. It is clean when
neither lists the domain and the daily check, or a health check no more
than 7 days old, answered clean, and unknown
when neither has a current answer (no daily check result, and the latest
health check is missing, over 7 days old or has no recognised status).
listedSince (UTC) is when Kenso first saw the domain listed: the earlier
of the day the daily check first saw the listing (kept across gaps in
that check) and the listing health check. It is set only when
blocklistVerdict is listed and omitted otherwise.
uriblGreyOnly is true when the latest health check, whatever
its age, lists the domain on URIBL grey alone ('grey_uribl_com' /
'URIBL grey'), a list of bulk senders: grey alone isn't a listing, so
it needs no action. blacklistStatus, listedCount and listedZones stay
the check exactly as it was recorded, so they can say listed for a
grey-only check, and they never show the daily check. Read
blocklistVerdict, not blacklistStatus, to tell whether the domain is
listed.
Staleness: the mail DNS verdicts, blacklistStatus, listedCount,
listedZones and uriblGreyOnly come from the last health snapshot, taken
by the daily health sweep or by a check you start, and checkedAt is when
it ran. They change only when a new check runs. blocklistVerdict can
change without one: it turns unknown once that check is over 7 days old
and nothing else answers, and it follows each run of the daily blocklist
check.
To refresh them now, call domain-health-checks-create (202 and a
domain_health job) on the same facade, poll the job until it completes,
then read get-health again. Tracking CNAMEs are get-dns and verify-dns,
not mail DNS.
list
Read. GET https://api.ken.so/v1/domains
Query: cursor string, limit integer
List domains in the current workspace, or find one by q. q: part of the name (acme finds acme.com). Requires Delivery view.
GET /api/v1/domains. Public. Sends Ken-Version 1.1.
client_id is sent as X-Ken-Workspace-Id.
status: active, expired, blacklisted, paused, banned, pending_setup, deleted.
source is platform_purchased or imported.
isPrimary is true for the workspace's primary domain (its email domain);
a member-owned inbox on it is a primary inbox (inbox isPrimary).
rampUp is { days, dayIndex, isComplete }: the send-volume ramp-up today,
as in "day dayIndex of days". days 0 means no ramp-up. dayIndex counts UTC
days from the ramp start and stays at days once it is over. isComplete is
true when the domain's inboxes send at their full daily limit. Omitted
when it could not be read.
campaignPixelHost is { status, hostname?, requiredRecord? }: where campaign
mail from the domain can load its open pixel, from stored state. status
link (link.{domain} serves), unsub (Kenso zone: Kenso creates unsub.{domain};
hostname is that expected host, not one confirmed to serve), none (no
host, so campaign mail goes out without a pixel; requiredRecord is the
CNAME { type, name, value } the owner adds when the DNS is outside Kenso)
or unknown (Kenso has not tried a host there yet, or is still trying).
Once public DNS shows the record, Kenso registers the host on its own,
usually within an hour, and status turns link after the host serves
(DEV-5612); no support step. Omitted when it could not be read. Separate from
openPixelHostname, the 1:1 pixel host.
replacedBy is { id, name }: the domain Kenso bought in this one's place,
such as after it landed on a blocklist. Omitted when nothing replaced it.
health is { rung, reason, message, action, since, until, evaluatedAt }:
the domain health rung (good, watch, throttle, quarantine, block), why,
and the next step. Only where domain health is on for the workspace.
list-health
Read. GET https://api.ken.so/v1/domains/health
Query: domainIds string
Return the latest health snapshot of up to 200 domains in one call, in the order of domain_ids. Each item is what get-health returns for that domain (same fields, same rules). An id that is not a domain of the workspace has no item. Full docs: describe_tools(['api_domains_list_health'])
GET /api/v1/domains/health?domainIds=4,9,12. Public. Sends Ken-Version 1.1. Requires Delivery view. domain_ids is required: 1 to 200 positive domain ids. A repeated id is read once. Items come in the order of domain_ids, each with domainId, so read get-health for what every field means (blocklistVerdict, uriblGreyOnly, the mail DNS verdicts, rates as fractions, and when they go stale). Use it instead of one get-health call per domain when you need several domains, such as every domain of a list page. An id outside the workspace, or a deleted domain, is left out instead of not_found, so compare the returned domainId values with the ids you sent. pagination.hasMore is always false.
list-own-domains
Read. GET https://api.ken.so/v1/workspaces/{workspaceId}/own-domains
Path: workspaceId
List the workspace's own domains: the Primary first, then added ones. Any member of the workspace can read them.
GET /api/v1/workspaces/{workspaceId}/own-domains with Ken-Version 1.1.
Internal exposure. Non-members get 404.
data[] items are {domain, isPrimary, createdAt}. The Primary is the
workspace's company email domain, listed first with isPrimary true and
no createdAt; it is absent when the workspace has none. Added domains
follow, oldest first, with isPrimary false. pagination.hasMore is always
false (at most 20 added domains).
Every listed domain counts as the company's own (DEV-3886): a mailbox
on any of them can be a primary inbox and send 1:1 email. isPrimary
only marks the sign-up email domain.
Reading also re-syncs the blocklist mirror of these domains when the
own_domain_exclusion feature flag is on for the workspace.
hosting-hostname-set
Write. PUT https://api.ken.so/v1/hosting/hostname
Query: purpose string
Body (json): domain string, subdomain string
Claim {subdomain}.{primary email domain} as the workspace hosting hostname and run one check. purpose="booking" sets the Scheduler host, optionally on another domain. Returns the CNAME record to add.
PUT /api/v1/hosting/hostname {subdomain, domain}. Internal. Sends Ken-Version
1.1. Requires Delivery edit access. subdomain is one DNS label such
as go. The backend claims {subdomain}.{primary email domain} and runs one
check at once, so the reply already says pending (with an error) or ready.
Sending the stored subdomain again only re-runs the check. A different
subdomain removes the old hostname first. Routes return 404 not_found
unless the workspace has the studio or accounts_send feature on.
purpose is studio (default) or booking. booking sets the workspace's
Scheduler host (needs the scheduler feature), and a different subdomain
keeps the old host as the previous one, which still serves links already
sent. domain (booking only) is the parent domain, for example acme.io for
meet.acme.io: any domain the workspace controls. Omitted, or the primary
email domain, claims on the primary email domain. On another domain the
reply says hostname_ownership_missing and carries ownershipRecord, the TXT
record that proves control. domain without purpose="booking" fails here.
Returns {hostname, subdomain, domain, status, error, dnsRecord,
ownershipRecord, readyAt, lastCheckedAt} (see
domains(operation="hosting-hostname-get")). After set, give the customer
dnsRecord (a CNAME) and ownershipRecord (a TXT record) when present, then
call domains(operation="hosting-hostname-verify") with the same purpose
once they resolve.
Refusals: primary_domain_missing, invalid_subdomain, invalid_domain,
subdomain_reserved, hostname_reserved, brand_domain (all 400) and
hostname_taken (409). brand_domain means the hostname is on a Kenso domain
(getken.dev, ken.so, ken.group, ...), including a workspace whose primary
domain is one: Scheduler links go into cold email, so never on a Kenso domain.
invalid_domain means domain is not a domain name (an IP, one label, a URL).
set and verify share one per-workspace limit (5 a minute, 720 a day by
default); over it the backend answers 429 rate_limited with Retry-After.
update
Write. PATCH https://api.ken.so/v1/domains/{domainId}
Path: domainId
Update a domain. Absent fields stay unchanged. Null clears redirect_url_404, ramp_up_days, tag_ids, and catch_all_email.
PATCH /api/v1/domains/{domainId}. Public. Sends Ken-Version 1.1.
Requires Delivery edit access (owners, admins and editors by default). auto_renew also needs the billing permission (admins by default).
masking_enabled and catch_all_email require SuperAdmin.
website_mode: page (Kenso's rebuild of the client's home page) or redirect; it cannot be cleared.
It is the person's answer to "What should people see when they open these domains? A rebuild of your website (recommended) or a redirect to your website?": ask them, never choose for them. Read it back with website(operation="outbound-site-domain-get", domain_id=...).
hosting-hostname-verify
Write. POST https://api.ken.so/v1/hosting/hostname/verify
Query: purpose string
Re-check the hosting hostname now (DNS, certificate, edge route, open pixel). A check that does not pass still succeeds: status stays pending and error says what is missing.
POST /api/v1/hosting/hostname/verify. Internal. Sends Ken-Version 1.1.
Requires Delivery edit access. Resets the retry backoff and runs one
check. A failed hostname starts over as pending. purpose is studio
(default) or booking (the current Scheduler host). Returns 404 not_found
when no hostname is set, or when the workspace has neither the studio nor
the accounts_send feature on (purpose=booking: scheduler). Shares the set
limit: 429 rate_limited with Retry-After over it.
Returns {hostname, subdomain, domain, status, error, dnsRecord, ownershipRecord, readyAt, lastCheckedAt}.
verify-dns
Write. POST https://api.ken.so/v1/domains/{domainId}/verify-dns
Path: domainId
Verify Kenso tracking DNS for one domain. Requires Delivery edit.
POST /api/v1/domains/{domainId}/verify-dns. Public. Sends Ken-Version 1.1.