Outbound domain pages
The outbound site is a one-page website Kenso builds from your company website and serves on your sending domains, so a prospect who opens one of those domains sees a real page instead of a redirect. Use these operations to edit the details the page shows, rebuild it, and restore an earlier version. A domain shows the page only when its website choice is page (websiteMode on PATCH /v1/domains/{domainId}). A rebuild runs in the background, and the rebuilds you start count against a limit per day and per 30 days.
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. |
Get the outbound site
/v1/outbound-siteoutbound-site.get- Permission
- Delivery view
- Rate limit
- 12,000 requests a minute per API key
domain_pages feature on your workspace. Until it is on, calls answer 404.Returns the outbound site: the details the page shows, the version that is live and the latest build.
Reading never creates the outbound site. A workspace that has none gets empty fields and showMainSiteLink: true. effectiveMainSiteUrl is the website the page links to and is rebuilt from: mainSiteUrl when it is set, else the workspace website.
Requires Delivery view.
curl -X GET "https://api.ken.so/v1/outbound-site" \
-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 OutboundSite.
Show the 9 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Update the outbound site
/v1/outbound-siteoutbound-site.update- Permission
- Delivery edit
- Rate limit
- 4,800 requests a minute per API key
domain_pages feature on your workspace. Until it is on, calls answer 404.Changes the details the outbound site page shows. Send only the fields you want to change: a field you leave out keeps its value, and null or an empty string clears a text field. The first update creates the outbound site.
mainSiteUrl is a public http or https URL of at most 2,048 characters. brandName and legalName are at most 200 characters, contactEmail is one email address, postalAddress is at most 500 characters, and showMainSiteLink is true or false. Before it saves, Kenso runs its link reputation check on the website the page will link to: mainSiteUrl, else the workspace website.
When a version is live, every domain that shows the page updates at once, with no rebuild. Example: {"contactEmail": "[email protected]", "showMainSiteLink": false}.
Errors:
400 validation_failed: a field breaks a rule, or the linked website fails the reputation check. The error has one detail per field, and nothing is saved.503 service_unavailable: the change was saved but the live page did not update. Send the same request again.
Requires Delivery edit.
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
mainSiteUrl | string | optional | The website the page links to and is rebuilt from: a public http or https URL of at most 2,048 characters. Null makes the page use the workspace website. |
brandName | string | optional | The brand name the page shows, at most 200 characters. |
contactEmail | string | optional | The public contact email the page shows, one address such as [email protected]. |
legalName | string | optional | The company's legal name for the page footer, at most 200 characters. |
postalAddress | string | optional | The postal address for the page footer, at most 500 characters. |
showMainSiteLink | boolean | optional | Whether the page shows a visible link to the main website: true or false. Null is refused. |
curl -X PATCH "https://api.ken.so/v1/outbound-site" \
-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 '{
"mainSiteUrl": "https://example.com",
"brandName": "string",
"contactEmail": "[email protected]",
"legalName": "string",
"postalAddress": "string",
"showMainSiteLink": true
}'Response 200
data is a OutboundSite.
Show the 9 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Get a domain's website
/v1/domains/{domainId}/websiteoutbound-site.domain-get- Permission
- Delivery view
- Rate limit
- 12,000 requests a minute per API key
domain_pages feature on your workspace. Until it is on, calls answer 404.Returns what a visitor sees on this domain: the domain's website choice and, for each hostname, whether Kenso serves the workspace's outbound site page there.
mode is unset (nobody chose yet, so the domain keeps sending visitors to its forwarding URL), redirect or page. Change it with websiteMode on PATCH /v1/domains/{domainId}. hostnames lists the bare domain first, then its www hostname, and is empty until Kenso has checked the domain.
Errors:
404 not_found: the workspace has no domain with this id.
Requires Delivery view.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
domainId | path | integer (int64) | required | The domain's id. |
curl -X GET "https://api.ken.so/v1/domains/812/website" \
-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 DomainWebsite.
Show the 4 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Rebuild the outbound site
/v1/outbound-site/refreshoutbound-site.refresh- Permission
- Delivery edit
- Rate limit
- 3 requests a day and 10 every 30 days per workspace
domain_pages feature on your workspace. Until it is on, calls answer 404.Queues a rebuild of the page from the linked website and answers 202 with the build. The live page changes when the build's status turns succeeded; follow it with latestRun on GET /v1/outbound-site.
An optional note of at most 1,000 characters tells Kenso what to change, such as {"note": "drop the pricing section"}. Each rebuild you start counts against the workspace's limit of 3 a day and 10 in 30 days. Rebuilds Kenso starts on its own (for the first page, a website change or a content change) and restores do not count.
Errors:
400 validation_failed:noteis longer than 1,000 characters.409 website_missing: neithermainSiteUrlnor the workspace website is set.409 run_in_progress: a build is already queued or running. Wait for it to finish.429 quota_exceeded: the workspace reached its rebuild limit, and nothing is queued.Retry-AfterandquotaResetAtsay when you can rebuild again.error.details[0]repeats the limit (limit), the reset time (resetAt) and the wait in seconds (retryAfterSeconds).
Requires Delivery edit.
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
note | string | optional | What to change in the rebuild, in plain words, such as "drop the pricing section". At most 1,000 characters. Omitted or empty rebuilds with no note. |
curl -X POST "https://api.ken.so/v1/outbound-site/refresh" \
-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 '{
"note": "string"
}'Response 202
data is a OutboundSiteRun.
Show the 10 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
List outbound site versions
/v1/outbound-site/versionsoutbound-site.versions-list- Permission
- Delivery view
- Rate limit
- 12,000 requests a minute per API key
domain_pages feature on your workspace. Until it is on, calls answer 404.Returns the versions of the outbound site page, newest first. Every build and every restore adds a version. The list holds at most 200 versions in one page, with no cursor. isCurrent marks the version that is live.
Requires Delivery view.
curl -X GET "https://api.ken.so/v1/outbound-site/versions" \
-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 OutboundSiteVersion. Each item has these fields. The response also carries pagination.
Show the 12 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Restore an outbound site version
/v1/outbound-site/versions/{versionId}/restoreoutbound-site.versions-restore- Permission
- Delivery edit
- Rate limit
- 4,800 requests a minute per API key
domain_pages feature on your workspace. Until it is on, calls answer 404.Makes an earlier version of the page live again. Kenso adds a copy of the version with source restored, makes the copy current and updates every domain that shows the page at once. Restoring the version that is already current only updates the domains again. A restore does not count against the rebuild limit. Returns the outbound site.
Errors:
400 validation_failed: the website the page links to fails the link reputation check, or the version's page fails today's page checks. A version saved under older rules can fail them. Then the error namespage_refusedonversionId, its message lists the problems, and Kenso saves and publishes nothing.404 not_found: the workspace has no version with this id.409 version_html_missing: the version's page is no longer stored.503 service_unavailable: send the request again. When the message says the live page did not update, the restore itself was saved.
Requires Delivery edit.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
versionId | path | integer (int64) | required | The id of the version to restore, from GET /v1/outbound-site/versions. |
curl -X POST "https://api.ken.so/v1/outbound-site/versions/812/restore" \
-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 OutboundSite.
Show the 9 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Get an outbound site preview link
/v1/outbound-site/previewoutbound-site.preview- Permission
- Delivery view
- Rate limit
- 12,000 requests a minute per API key
domain_pages feature on your workspace. Until it is on, calls answer 404.Returns a signed link that shows the live version of the page as one domain serves it, filled in for that domain. Show it in a frame. The link works for one hour, until expiresAt, so get a new one before then. In a demo workspace, url is the page itself as a data:text/html URL.
Errors:
400 validation_failed:domainIdis missing.404 not_found: the workspace has no domain with this id, or no version is published yet.503 service_unavailable: previews are not available right now. Try again later.
Requires Delivery view.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
domainId | query | integer (int64) | optional | The domain to preview the page on. |
curl -X GET "https://api.ken.so/v1/outbound-site/preview" \
-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 OutboundSitePreviewLink.
Show the 2 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
More in Deliverability:DomainsDomain health checksPlacement testsDelivery settingsTracking linksInfrastructure findingsDeliverability rulesAll resources