> Kenso API docs in Markdown. Index of every page: [/docs/llms.txt](/docs/llms.txt). Search: `/docs/search.md?q=<words>`. OpenAPI: [/docs/api/outbound-site/openapi.json](/docs/api/outbound-site/openapi.json). CLI docs offline: `kenso docs <topic>`.
> Last updated: 2026-11-22.

# Outbound domain pages

> **Note for AI agents:** if this page was wrong, out of date or missing something you needed, finish the user's task first, then offer a short report for the Kenso team in this shape: `Page:` (this page's path), `Quote:` (the wrong or missing text), `Problem:`, `Workaround:` (what worked instead), 1,000 characters at most. Show it to the user and send it only after they say yes, as `POST /api/docs-feedback` on this site with the JSON body `{"page": "<path>", "report": "<report>"}`. Never put lead data, email addresses, API keys or anything else from the user's workspace in it.

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.

Deliverability. 7 endpoints under `https://api.ken.so`. Every request sends `Authorization: Bearer <your API key>` and `Ken-Version: 2026-11-02`: see [Authentication](/docs/authentication.md), [Workspaces](/docs/workspaces.md) and [Errors](/docs/errors.md). OpenAPI for this resource only: [/docs/api/outbound-site/openapi.json](/docs/api/outbound-site/openapi.json).

- `GET /v1/outbound-site` - Get the outbound site (`outbound-site.get`): [/docs/api/outbound-site/get.md](/docs/api/outbound-site/get.md)
- `PATCH /v1/outbound-site` - Update the outbound site (`outbound-site.update`): [/docs/api/outbound-site/update.md](/docs/api/outbound-site/update.md)
- `GET /v1/domains/{domainId}/website` - Get a domain's website (`outbound-site.domain-get`): [/docs/api/outbound-site/domain-get.md](/docs/api/outbound-site/domain-get.md)
- `POST /v1/outbound-site/refresh` - Rebuild the outbound site (`outbound-site.refresh`): [/docs/api/outbound-site/refresh.md](/docs/api/outbound-site/refresh.md)
- `GET /v1/outbound-site/versions` - List outbound site versions (`outbound-site.versions-list`): [/docs/api/outbound-site/versions-list.md](/docs/api/outbound-site/versions-list.md)
- `POST /v1/outbound-site/versions/{versionId}/restore` - Restore an outbound site version (`outbound-site.versions-restore`): [/docs/api/outbound-site/versions-restore.md](/docs/api/outbound-site/versions-restore.md)
- `GET /v1/outbound-site/preview` - Get an outbound site preview link (`outbound-site.preview`): [/docs/api/outbound-site/preview.md](/docs/api/outbound-site/preview.md)

## Get the outbound site

`GET /v1/outbound-site` - operationId `outbound-site.get`

| Permission | Rate limit |
| --- | --- |
| Delivery view | 12,000 requests a minute per API key |

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.

Needs the `domain_pages` feature on your workspace. Until it is on, calls answer 404.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/outbound-site/GET/v1/outbound-site)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | 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 value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | 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`. |

### Response 200

`data` is a `OutboundSite`.

| Field | Type | Description |
| --- | --- | --- |
| `mainSiteUrl` | string | The website you set for the page to link to and be rebuilt from. Omitted when the page uses the workspace website. |
| `effectiveMainSiteUrl` | string | The website the page links to and is rebuilt from: `mainSiteUrl`, else the workspace website. Omitted when neither is set. |
| `brandName` | string | The brand name the page shows. Omitted when not set. |
| `contactEmail` | string | The public contact email the page shows. Omitted when not set. |
| `legalName` | string | The company's legal name in the page footer. Omitted when not set. |
| `postalAddress` | string | The postal address in the page footer. Omitted when not set. |
| `showMainSiteLink` | boolean | True when the page shows a visible link to the main website. True until you change it. |
| `currentVersion` | OutboundSiteVersion | The version that every domain showing the page serves now. Omitted before the first build. |
| `latestRun` | OutboundSiteRun | The newest build, whatever its status. Omitted before the first build. |

### Request

```bash
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"
```

### Example response

```json
{
  "success": true,
  "data": {
    "mainSiteUrl": "https://example.com",
    "effectiveMainSiteUrl": "https://example.com",
    "brandName": "string",
    "contactEmail": "jane@example.com",
    "legalName": "string",
    "postalAddress": "string",
    "showMainSiteLink": true,
    "currentVersion": {
      "id": 812,
      "source": "string",
      "note": "string",
      "htmlBytes": 1,
      "assetBytes": 1,
      "rounds": 1,
      "model": "string",
      "isBelowThreshold": true,
      "isCurrent": true,
      "runId": 812,
      "createdByUserId": 812,
      "createdAt": "2026-09-23T15:02:11Z"
    },
    "latestRun": {
      "id": 812,
      "status": "queued",
      "trigger": "string",
      "note": "string",
      "versionId": 812,
      "error": "string",
      "requestedByUserId": 812,
      "createdAt": "2026-09-23T15:02:11Z",
      "startedAt": "2026-09-23T15:02:11Z",
      "finishedAt": "2026-09-23T15:02:11Z"
    }
  }
}
```

## Update the outbound site

`PATCH /v1/outbound-site` - operationId `outbound-site.update`

| Permission | Rate limit |
| --- | --- |
| Delivery edit | 4,800 requests a minute per API key |

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": "hello@acme.com", "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.

Needs the `domain_pages` feature on your workspace. Until it is on, calls answer 404.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/outbound-site/PATCH/v1/outbound-site)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | 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 value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | 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`. |

### Request body

`application/json`, optional.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `mainSiteUrl` | string | no | 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 | no | The brand name the page shows, at most 200 characters. |
| `contactEmail` | string | no | The public contact email the page shows, one address such as `hello@acme.com`. |
| `legalName` | string | no | The company's legal name for the page footer, at most 200 characters. |
| `postalAddress` | string | no | The postal address for the page footer, at most 500 characters. |
| `showMainSiteLink` | boolean | no | Whether the page shows a visible link to the main website: true or false. Null is refused. |

### Response 200

`data` is a `OutboundSite`.

| Field | Type | Description |
| --- | --- | --- |
| `mainSiteUrl` | string | The website you set for the page to link to and be rebuilt from. Omitted when the page uses the workspace website. |
| `effectiveMainSiteUrl` | string | The website the page links to and is rebuilt from: `mainSiteUrl`, else the workspace website. Omitted when neither is set. |
| `brandName` | string | The brand name the page shows. Omitted when not set. |
| `contactEmail` | string | The public contact email the page shows. Omitted when not set. |
| `legalName` | string | The company's legal name in the page footer. Omitted when not set. |
| `postalAddress` | string | The postal address in the page footer. Omitted when not set. |
| `showMainSiteLink` | boolean | True when the page shows a visible link to the main website. True until you change it. |
| `currentVersion` | OutboundSiteVersion | The version that every domain showing the page serves now. Omitted before the first build. |
| `latestRun` | OutboundSiteRun | The newest build, whatever its status. Omitted before the first build. |

### Request

```bash
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": "hello@acme.com",
  "legalName": "string",
  "postalAddress": "string",
  "showMainSiteLink": true
}'
```

### Example response

```json
{
  "success": true,
  "data": {
    "mainSiteUrl": "https://example.com",
    "effectiveMainSiteUrl": "https://example.com",
    "brandName": "string",
    "contactEmail": "jane@example.com",
    "legalName": "string",
    "postalAddress": "string",
    "showMainSiteLink": true,
    "currentVersion": {
      "id": 812,
      "source": "string",
      "note": "string",
      "htmlBytes": 1,
      "assetBytes": 1,
      "rounds": 1,
      "model": "string",
      "isBelowThreshold": true,
      "isCurrent": true,
      "runId": 812,
      "createdByUserId": 812,
      "createdAt": "2026-09-23T15:02:11Z"
    },
    "latestRun": {
      "id": 812,
      "status": "queued",
      "trigger": "string",
      "note": "string",
      "versionId": 812,
      "error": "string",
      "requestedByUserId": 812,
      "createdAt": "2026-09-23T15:02:11Z",
      "startedAt": "2026-09-23T15:02:11Z",
      "finishedAt": "2026-09-23T15:02:11Z"
    }
  }
}
```

## Get a domain's website

`GET /v1/domains/{domainId}/website` - operationId `outbound-site.domain-get`

| Permission | Rate limit |
| --- | --- |
| Delivery view | 12,000 requests a minute per API key |

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.

Needs the `domain_pages` feature on your workspace. Until it is on, calls answer 404.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/domains/GET/v1/domains/%7BdomainId%7D/website)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `domainId` | path | integer (int64) | yes | The domain's id. |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | 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 value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | 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`. |

### Response 200

`data` is a `DomainWebsite`.

| Field | Type | Description |
| --- | --- | --- |
| `domainId` | integer (int64) | The domain's id. |
| `mode` | string | The domain's website choice: `unset` (nobody chose yet, so the domain keeps sending visitors to its forwarding URL), `redirect` or `page`. |
| `currentVersionId` | integer (int64) | Id of the outbound site page version the workspace serves now. Omitted until a page was published. |
| `hostnames` | array of DomainWebsiteHostname | The domain's hostnames: the bare domain first, then its `www` hostname. Empty until Kenso has checked the domain. |

### Request

```bash
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"
```

### Example response

```json
{
  "success": true,
  "data": {
    "domainId": 812,
    "mode": "string",
    "currentVersionId": 812,
    "hostnames": [
      {
        "hostname": "acme-mail.com",
        "attachPath": "worker_route",
        "dnsWriter": "string",
        "dnsWriterKind": "string",
        "status": "string",
        "sslStatus": "active",
        "unsupportedReason": "string",
        "checkedAt": "2026-09-23T15:02:11Z",
        "lastError": "string",
        "stopped": true
      }
    ]
  }
}
```

## Rebuild the outbound site

`POST /v1/outbound-site/refresh` - operationId `outbound-site.refresh`

| Permission | Rate limit |
| --- | --- |
| Delivery edit | 3 requests a day and 10 every 30 days per workspace |

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.

Needs the `domain_pages` feature on your workspace. Until it is on, calls answer 404.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/outbound-site/POST/v1/outbound-site/refresh)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | 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 value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | 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`. |

### Request body

`application/json`, optional.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `note` | string | no | 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. |

### Response 202

`data` is a `OutboundSiteRun`.

| Field | Type | Description |
| --- | --- | --- |
| `id` | integer (int64) | The build's id. |
| `status` | string | The build's state: `queued`, `running`, `succeeded`, `failed` or `canceled`. The live page changes only when a build succeeds. |
| `trigger` | string | What started the build: `first_page_domain` (the first domain set to show the page), `refresh` (a rebuild a member started), `refresh_with_note` (a rebuild with a note), `website_changed` (the linked website changed) or `content_changed` (Kenso found new content on the linked website). |
| `note` | string | The note sent with the rebuild. Omitted when there is none. |
| `versionId` | integer (int64) | The version the build made. Omitted until the build succeeds. |
| `error` | string | Why the build failed. Omitted when it did not fail. |
| `requestedByUserId` | integer (int64) | The member who started the build. Omitted for a build Kenso started on its own. |
| `createdAt` | string (date-time) | When the build was queued, in UTC. |
| `startedAt` | string (date-time) | When the build started, in UTC. Omitted while it is queued. |
| `finishedAt` | string (date-time) | When the build ended, in UTC. Omitted until it ends. |

### Request

```bash
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"
}'
```

### Example response

```json
{
  "success": true,
  "data": {
    "id": 812,
    "status": "queued",
    "trigger": "string",
    "note": "string",
    "versionId": 812,
    "error": "string",
    "requestedByUserId": 812,
    "createdAt": "2026-09-23T15:02:11Z",
    "startedAt": "2026-09-23T15:02:11Z",
    "finishedAt": "2026-09-23T15:02:11Z"
  }
}
```

## List outbound site versions

`GET /v1/outbound-site/versions` - operationId `outbound-site.versions-list`

| Permission | Rate limit |
| --- | --- |
| Delivery view | 12,000 requests a minute per API key |

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.

Needs the `domain_pages` feature on your workspace. Until it is on, calls answer 404.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/outbound-site/GET/v1/outbound-site/versions)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | 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 value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | 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`. |

### Response 200

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

| Field | Type | Description |
| --- | --- | --- |
| `id` | integer (int64) | The version's id. |
| `source` | string | How the version was made: `generated` (a build), `regenerated_with_note` (a rebuild with a note) or `restored` (the copy a restore made). |
| `note` | string | The note the version was built with. On a restored copy, it names the version it came from. Omitted when there is none. |
| `htmlBytes` | integer (int64) | Size of the page's HTML, in bytes. |
| `assetBytes` | integer (int64) | Total size of the page's other files, such as images, in bytes. |
| `rounds` | integer (int32) | How many rounds the build took to reach this page. Omitted when not recorded. |
| `model` | string | The AI model that built the page. Omitted when not recorded. |
| `isBelowThreshold` | boolean | True when the build's visual check scored the page below its threshold. The page still went live, so it is worth a look. |
| `isCurrent` | boolean | True for the version that is live. |
| `runId` | integer (int64) | The build that made this version. Omitted when the version did not come from a build. |
| `createdByUserId` | integer (int64) | The member who started the build or restore. Omitted when Kenso made the version on its own. |
| `createdAt` | string (date-time) | When the version was made, in UTC. |

### Request

```bash
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"
```

### Example response

```json
{
  "success": true,
  "data": [
    {
      "id": 812,
      "source": "string",
      "note": "string",
      "htmlBytes": 1,
      "assetBytes": 1,
      "rounds": 1,
      "model": "string",
      "isBelowThreshold": true,
      "isCurrent": true,
      "runId": 812,
      "createdByUserId": 812,
      "createdAt": "2026-09-23T15:02:11Z"
    }
  ],
  "pagination": {
    "nextCursor": "eyJpZCI6ODE1fQ",
    "hasMore": true,
    "total": 1,
    "totalCount": 1,
    "isTotalCapped": true
  }
}
```

## Restore an outbound site version

`POST /v1/outbound-site/versions/{versionId}/restore` - operationId `outbound-site.versions-restore`

| Permission | Rate limit |
| --- | --- |
| Delivery edit | 4,800 requests a minute per API key |

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.

Needs the `domain_pages` feature on your workspace. Until it is on, calls answer 404.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/outbound-site/POST/v1/outbound-site/versions/%7BversionId%7D/restore)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `versionId` | path | integer (int64) | yes | The id of the version to restore, from `GET /v1/outbound-site/versions`. |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | 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 value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | 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`. |

### Response 200

`data` is a `OutboundSite`.

| Field | Type | Description |
| --- | --- | --- |
| `mainSiteUrl` | string | The website you set for the page to link to and be rebuilt from. Omitted when the page uses the workspace website. |
| `effectiveMainSiteUrl` | string | The website the page links to and is rebuilt from: `mainSiteUrl`, else the workspace website. Omitted when neither is set. |
| `brandName` | string | The brand name the page shows. Omitted when not set. |
| `contactEmail` | string | The public contact email the page shows. Omitted when not set. |
| `legalName` | string | The company's legal name in the page footer. Omitted when not set. |
| `postalAddress` | string | The postal address in the page footer. Omitted when not set. |
| `showMainSiteLink` | boolean | True when the page shows a visible link to the main website. True until you change it. |
| `currentVersion` | OutboundSiteVersion | The version that every domain showing the page serves now. Omitted before the first build. |
| `latestRun` | OutboundSiteRun | The newest build, whatever its status. Omitted before the first build. |

### Request

```bash
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"
```

### Example response

```json
{
  "success": true,
  "data": {
    "mainSiteUrl": "https://example.com",
    "effectiveMainSiteUrl": "https://example.com",
    "brandName": "string",
    "contactEmail": "jane@example.com",
    "legalName": "string",
    "postalAddress": "string",
    "showMainSiteLink": true,
    "currentVersion": {
      "id": 812,
      "source": "string",
      "note": "string",
      "htmlBytes": 1,
      "assetBytes": 1,
      "rounds": 1,
      "model": "string",
      "isBelowThreshold": true,
      "isCurrent": true,
      "runId": 812,
      "createdByUserId": 812,
      "createdAt": "2026-09-23T15:02:11Z"
    },
    "latestRun": {
      "id": 812,
      "status": "queued",
      "trigger": "string",
      "note": "string",
      "versionId": 812,
      "error": "string",
      "requestedByUserId": 812,
      "createdAt": "2026-09-23T15:02:11Z",
      "startedAt": "2026-09-23T15:02:11Z",
      "finishedAt": "2026-09-23T15:02:11Z"
    }
  }
}
```

## Get an outbound site preview link

`GET /v1/outbound-site/preview` - operationId `outbound-site.preview`

| Permission | Rate limit |
| --- | --- |
| Delivery view | 12,000 requests a minute per API key |

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.

Needs the `domain_pages` feature on your workspace. Until it is on, calls answer 404.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/outbound-site/GET/v1/outbound-site/preview)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `domainId` | query | integer (int64) | no | The domain to preview the page on. |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | 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 value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | 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`. |

### Response 200

`data` is a `OutboundSitePreviewLink`.

| Field | Type | Description |
| --- | --- | --- |
| `url` | string | The signed preview link. Show it in a frame. In a demo workspace, it is the page itself as a `data:text/html` URL. |
| `expiresAt` | string (date-time) | When the link stops working, in UTC, one hour after it was made. Get a new one before then. |

### Request

```bash
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"
```

### Example response

```json
{
  "success": true,
  "data": {
    "url": "https://example.com",
    "expiresAt": "2026-09-23T15:02:11Z"
  }
}
```

## Types

Each named type the tables above use, nested ones included.

### OutboundSiteVersion

One version of the outbound site page.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer (int64) | no | The version's id. |
| `source` | string | no | How the version was made: `generated` (a build), `regenerated_with_note` (a rebuild with a note) or `restored` (the copy a restore made). |
| `note` | string | no | The note the version was built with. On a restored copy, it names the version it came from. Omitted when there is none. |
| `htmlBytes` | integer (int64) | no | Size of the page's HTML, in bytes. |
| `assetBytes` | integer (int64) | no | Total size of the page's other files, such as images, in bytes. |
| `rounds` | integer (int32) | no | How many rounds the build took to reach this page. Omitted when not recorded. |
| `model` | string | no | The AI model that built the page. Omitted when not recorded. |
| `isBelowThreshold` | boolean | no | True when the build's visual check scored the page below its threshold. The page still went live, so it is worth a look. |
| `isCurrent` | boolean | no | True for the version that is live. |
| `runId` | integer (int64) | no | The build that made this version. Omitted when the version did not come from a build. |
| `createdByUserId` | integer (int64) | no | The member who started the build or restore. Omitted when Kenso made the version on its own. |
| `createdAt` | string (date-time) | no | When the version was made, in UTC. |

### OutboundSiteRun

One build of the outbound site page.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer (int64) | no | The build's id. |
| `status` | string | no | The build's state: `queued`, `running`, `succeeded`, `failed` or `canceled`. The live page changes only when a build succeeds. |
| `trigger` | string | no | What started the build: `first_page_domain` (the first domain set to show the page), `refresh` (a rebuild a member started), `refresh_with_note` (a rebuild with a note), `website_changed` (the linked website changed) or `content_changed` (Kenso found new content on the linked website). |
| `note` | string | no | The note sent with the rebuild. Omitted when there is none. |
| `versionId` | integer (int64) | no | The version the build made. Omitted until the build succeeds. |
| `error` | string | no | Why the build failed. Omitted when it did not fail. |
| `requestedByUserId` | integer (int64) | no | The member who started the build. Omitted for a build Kenso started on its own. |
| `createdAt` | string (date-time) | no | When the build was queued, in UTC. |
| `startedAt` | string (date-time) | no | When the build started, in UTC. Omitted while it is queued. |
| `finishedAt` | string (date-time) | no | When the build ended, in UTC. Omitted until it ends. |

### DomainWebsiteHostname

Whether Kenso serves the outbound site page on one hostname of a domain.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `hostname` | string | no | The hostname, such as `acme-mail.com` or `www.acme-mail.com`. |
| `attachPath` | string | no | How Kenso serves the page on this hostname: `worker_route` or `custom_hostname`. Omitted when the hostname cannot show the page; `unsupportedReason` says why. |
| `dnsWriter` | string | no | The DNS host through which Kenso writes this hostname's records, as a code for Kenso's DNS, the mailbox provider or the registrar. Omitted when Kenso cannot write them. Prefer dnsWriterKind. |
| `dnsWriterKind` | string | no | Who writes this hostname's DNS records, in neutral words: `kenso` when Kenso writes them (through Kenso's DNS, the mailbox provider or the registrar), or `other`. Omitted when Kenso cannot write them. |
| `status` | string | no | Whether the page is on this hostname: `detached` (not served), `attaching`, `active` (served), `detaching` or `failed`. |
| `sslStatus` | string | no | State of the hostname's SSL certificate as Kenso's edge reports it, such as `active`. Only set for `custom_hostname`; omitted otherwise. |
| `unsupportedReason` | string | no | Why this hostname cannot show the page: `unknown_dns_host` (Kenso cannot write the domain's DNS), `dns_lookup_failed`, `smtp_farm_apex` (the domain points at a mail server and needs a manual check) or `foreign_link_host` (the hostname serves another workspace's links). Omitted when it can show the page. |
| `checkedAt` | string (date-time) | no | When Kenso last checked or changed this hostname, in UTC. Omitted before the first check. |
| `lastError` | string | no | Why Kenso's last attempt to put the page on this hostname, or take it off, failed: one short fixed sentence with no trailing period. Omitted when the last attempt did not fail. |
| `stopped` | boolean | no | True when Kenso stopped retrying after repeated failures. It starts again when the domain's website choice or its DNS changes: switching the domain to `redirect` and back restarts it. |

All resources: [/docs.md](/docs.md).
