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

# Analytics: Get workspace deliverability

> **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.

One endpoint of [Analytics](/docs/api/analytics.md). Authentication, workspaces and errors: [/docs.md](/docs.md).

## Get workspace deliverability

`GET /v1/analytics/deliverability` - operationId `analytics.get-deliverability`

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

Returns the workspace's sending health over a window: sends, replies, bounces, clicks and spam complaints, with
inbox and domain counts. Split it by day, by domain or by inbox.

`from` and `to` are required, and the window is at most 366 days. `groupBy` is `day` (the
default), `domain` or `inbox`. `limit` caps the domain and inbox rows, from 1 to 200, default 50.
Days are UTC calendar days. With an IANA `timeZone` other than UTC, the rows count sends, replies, bounces and
out-of-office replies on that zone's days, from its midnight on `from` to its midnight after `to`. The
window `sentCount`, `replyCount`, `bounceCount`, `clickCount` and rates are then the sums of
the day rows. Complaints always stay on UTC days, because Kenso stores them per UTC day.

Domain and inbox rows carry `reputation` and `alerts`. Kenso builds the alerts from send pauses,
blocklists, SPF, DKIM and DMARC checks, placement tests, complaints and recipient refusals. Inbox rows also get
alerts from bounce rates, Microsoft tenant bans and sender rejections, plus their domain's alerts. Reputation and
alerts describe the state now: only the `complaint_rate` and `high_bounce_rate` alerts count the window.

Errors:

- `400 validation_failed`: `from` or `to` is missing, the window is too long, or `groupBy`, `limit` or `timeZone` is not valid.

Requires Campaigns view.

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

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `from` | query | string (date-time) | no | First day of the window, an ISO 8601 date such as `2026-10-01`. Required. |
| `to` | query | string (date-time) | no | Last day of the window, inclusive, an ISO 8601 date. Required, on or after `from` and at most 366 days later. |
| `groupBy` | query | string | no | How to split the rows: `day` (default), `domain` or `inbox`. |
| `timeZone` | query | string | no | IANA time zone whose calendar days the window and rows use, such as `America/New_York`. Default UTC. |
| `limit` | query | integer (int32) | no | Most domain or inbox rows to return, from 1 to 200, default 50. Day rows are not capped. |
| `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 `Deliverability`.

| Field | Type | Description |
| --- | --- | --- |
| `from` | string (date-time) | The start of the window, in UTC. |
| `to` | string (date-time) | The end of the window, in UTC. |
| `groupBy` | string | How `rows` are grouped: `day`, `domain` or `inbox`. |
| `timeZone` | string | The IANA time zone the call asked for. Omitted when none was sent, and days are then UTC days. |
| `metrics` | DeliverabilityMetrics | The window's totals and the workspace's inbox counts. |
| `rows` | array of DeliverabilityRow | One row per day, domain or inbox, as `groupBy` asks. |

### Request

```bash
curl -X GET "https://api.ken.so/v1/analytics/deliverability?limit=50" \
  -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": {
    "from": "2026-09-23T15:02:11Z",
    "to": "2026-09-23T15:02:11Z",
    "groupBy": "day",
    "timeZone": "string",
    "metrics": {
      "sentCount": 1,
      "replyCount": 1,
      "bounceCount": 1,
      "clickCount": 1,
      "replyRate": 0.5,
      "bounceRate": 0.5,
      "clickRate": 0.5,
      "inboxCount": 1,
      "activeInboxCount": 1,
      "domainCount": 1,
      "inboxesPerDomain": 0.5,
      "healthyInboxCount": 1,
      "lowActivityInboxCount": 1,
      "inactiveInboxCount": 1,
      "complaintCount": 1,
      "complaintRate": 0.5
    },
    "rows": [
      {
        "date": "string",
        "domainId": 812,
        "domainName": "string",
        "inboxId": 812,
        "email": "jane@example.com",
        "inboxCount": 1,
        "sentCount": 1,
        "replyCount": 1,
        "bounceCount": 1,
        "clickCount": 1,
        "replyRate": 0.5,
        "bounceRate": 0.5,
        "clickRate": 0.5,
        "complaintCount": 1,
        "oooCount": 1,
        "oooRate": 0.5,
        "reputation": "string",
        "alerts": [
          {
            "code": "sending_paused",
            "scope": "domain",
            "severity": "warning",
            "message": "string",
            "action": "string",
            "since": "2026-09-23T15:02:11Z",
            "until": "2026-09-23T15:02:11Z",
            "rate": 0.5,
            "threshold": 0.5
          }
        ],
        "domainHealth": {
          "rung": "string",
          "reason": "string",
          "message": "string",
          "action": "string",
          "since": "2026-09-23T15:02:11Z",
          "until": "2026-09-23T15:02:11Z",
          "evaluatedAt": "2026-09-23T15:02:11Z"
        }
      }
    ]
  }
}
```

## Types

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

### DeliverabilityMetrics

The window's totals and the workspace's inbox counts. Rates are fractions from 0 to 1, omitted when nothing was sent.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `sentCount` | integer (int64) | no | Emails sent. |
| `replyCount` | integer (int64) | no | Replies, not counting out-of-office replies. |
| `bounceCount` | integer (int64) | no | Emails that bounced. |
| `clickCount` | integer (int64) | no | Link clicks. |
| `replyRate` | number (double) | no | Reply rate: `replyCount` divided by `sentCount`. |
| `bounceRate` | number (double) | no | Bounce rate: `bounceCount` divided by `sentCount`. |
| `clickRate` | number (double) | no | Click rate: `clickCount` divided by `sentCount`. |
| `inboxCount` | integer (int32) | no | Every inbox in the workspace, whatever its status. |
| `activeInboxCount` | integer (int32) | no | Inboxes whose status is active. |
| `domainCount` | integer (int32) | no | Domains in the workspace. |
| `inboxesPerDomain` | number (double) | no | Average inboxes per domain: `inboxCount` divided by `domainCount`, rounded to 1 decimal. Omitted when the workspace has no domain. |
| `healthyInboxCount` | integer (int32) | no | Inboxes the inbox provider's health check rates healthy. |
| `lowActivityInboxCount` | integer (int32) | no | Inboxes the inbox provider's health check rates low activity. |
| `inactiveInboxCount` | integer (int32) | no | Inboxes the inbox provider's health check rates inactive. |
| `complaintCount` | integer (int64) | no | Spam complaints in the window. Omitted when the complaint data could not be read. |
| `complaintRate` | number (double) | no | Complaint rate: `complaintCount` divided by `sentCount`, as a fraction from 0 to 1. Omitted when nothing was sent. |

### DeliverabilityRow

One day, domain or inbox of sending health. Rates are fractions from 0 to 1, omitted when nothing was sent.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `date` | string | no | Day rows only: the date as `YYYY-MM-DD`. |
| `domainId` | integer (int64) | no | The domain's id, on domain and inbox rows. |
| `domainName` | string | no | The domain name, on domain and inbox rows. |
| `inboxId` | integer (int64) | no | Inbox rows only: the inbox's id. |
| `email` | string | no | Inbox rows only: the inbox's email address. |
| `inboxCount` | integer (int32) | no | Domain rows only: the domain's inboxes. |
| `sentCount` | integer (int64) | no | Emails sent. |
| `replyCount` | integer (int64) | no | Replies, not counting out-of-office replies. |
| `bounceCount` | integer (int64) | no | Emails that bounced. |
| `clickCount` | integer (int64) | no | Link clicks. |
| `replyRate` | number (double) | no | Reply rate: `replyCount` divided by `sentCount`. |
| `bounceRate` | number (double) | no | Bounce rate: `bounceCount` divided by `sentCount`. |
| `clickRate` | number (double) | no | Click rate: `clickCount` divided by `sentCount`. |
| `complaintCount` | integer (int64) | no | Spam complaints, on day and domain rows. Omitted on inbox rows and when the complaint data could not be read. |
| `oooCount` | integer (int64) | no | Out-of-office replies, on domain and inbox rows. Omitted on day rows and when the count could not be read. |
| `oooRate` | number (double) | no | Out-of-office rate: `oooCount` divided by `sentCount`. Omitted on day rows and when nothing was sent. |
| `reputation` | string | no | Domain and inbox rows: `paused` (an active Kenso pause covers the row), `at_risk` (a critical alert), `watch` (a warning alert), `good` (no alert) or `unknown` (a signal could not be read, or there is no recent evidence). Omitted on day rows. It describes the state now: only the `complaint_rate` and `high_bounce_rate` alerts look at the requested window. |
| `alerts` | array of DeliverabilityAlert | no | Domain and inbox rows: plain-language alerts, empty when nothing is wrong. An inbox row also carries its domain's alerts, with `scope` set to `domain`. Omitted on day rows. |
| `domainHealth` | DomainHealthStatus | no | Domain and inbox rows in a workspace where domain health is on: the domain's health rung (`good`, `watch`, `throttle`, `quarantine`, `block`), reason, message and next step, as `health` on the domain. An inbox row carries its domain's. Omitted otherwise and on day rows. |

### DeliverabilityAlert

A problem with a domain's or inbox's sending.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `code` | string | no | The problem: `sending_paused`, `blocklisted`, `authentication_failing`, `dmarc_failing`, `placement_spam`, `placement_low_inbox`, `complaint_rate`, `microsoft_tenant_ban`, `sender_rejections`, `high_bounce_rate` or `recipient_refusals`. Expect new codes over time. |
| `scope` | string | no | What the alert is about: `domain` or `inbox`. |
| `severity` | string | no | How serious it is: `warning` or `critical`. |
| `message` | string | no | One plain sentence that states the problem with its number. |
| `action` | string | no | One sentence on what to do. |
| `since` | string (date-time) | no | When the signal was seen, in UTC. Omitted when unknown. |
| `until` | string (date-time) | no | When the pause ends, in UTC. Only on `sending_paused`. |
| `rate` | number (double) | no | The rate behind the alert, as a fraction from 0 to 1. Omitted when no rate drives it. |
| `threshold` | number (double) | no | The threshold the rate crossed, as a fraction from 0 to 1. Omitted when no rate drives it. |

### DomainHealthStatus

A domain's health on Ken's domain health ladder, customer-facing: `rung` is `good`, `watch`, `throttle`, `quarantine` or `block`; `reason` is a vendor-neutral code; `message` and `action` are sentences to show a user (`action` omitted when there is nothing to do); `until` is the end of a quarantine.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `rung` | string | no |  |
| `reason` | string | no |  |
| `message` | string | no |  |
| `action` | string | no |  |
| `since` | string (date-time) | no |  |
| `until` | string (date-time) | no |  |
| `evaluatedAt` | string (date-time) | no |  |
