Skip to Content
Deliverability

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.

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

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.

Get the outbound site

GET/v1/outbound-siteoutbound-site.get
Permission
Delivery view
Rate limit
12,000 requests a minute per API key
Needs the domain_pages feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

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.

Request
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

PATCH/v1/outbound-siteoutbound-site.update
Permission
Delivery edit
Rate limit
4,800 requests a minute per API key
Needs the domain_pages feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

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.

FieldTypeRequiredDescription
mainSiteUrlstringoptionalThe 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.
brandNamestringoptionalThe brand name the page shows, at most 200 characters.
contactEmailstringoptionalThe public contact email the page shows, one address such as [email protected].
legalNamestringoptionalThe company's legal name for the page footer, at most 200 characters.
postalAddressstringoptionalThe postal address for the page footer, at most 500 characters.
showMainSiteLinkbooleanoptionalWhether the page shows a visible link to the main website: true or false. Null is refused.
Request
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

GET/v1/domains/{domainId}/websiteoutbound-site.domain-get
Permission
Delivery view
Rate limit
12,000 requests a minute per API key
Needs the domain_pages feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

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

NameInTypeRequiredDescription
domainIdpathinteger (int64)requiredThe domain's id.
Request
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

POST/v1/outbound-site/refreshoutbound-site.refresh
Permission
Delivery edit
Rate limit
3 requests a day and 10 every 30 days per workspace
Needs the domain_pages feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

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: note is longer than 1,000 characters.
  • 409 website_missing: neither mainSiteUrl nor 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-After and quotaResetAt say 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.

FieldTypeRequiredDescription
notestringoptionalWhat 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.
Request
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

GET/v1/outbound-site/versionsoutbound-site.versions-list
Permission
Delivery view
Rate limit
12,000 requests a minute per API key
Needs the domain_pages feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

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.

Request
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

POST/v1/outbound-site/versions/{versionId}/restoreoutbound-site.versions-restore
Permission
Delivery edit
Rate limit
4,800 requests a minute per API key
Needs the domain_pages feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

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 names page_refused on versionId, 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

NameInTypeRequiredDescription
versionIdpathinteger (int64)requiredThe id of the version to restore, from GET /v1/outbound-site/versions.
Request
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

GET/v1/outbound-site/previewoutbound-site.preview
Permission
Delivery view
Rate limit
12,000 requests a minute per API key
Needs the domain_pages feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

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: domainId is 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

NameInTypeRequiredDescription
domainIdqueryinteger (int64)optionalThe domain to preview the page on.
Request
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.


On this page