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

# Copy grades

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

Grade email or LinkedIn copy before you send it.

Copy and personalization. 1 endpoint 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/email-copy-grades/openapi.json](/docs/api/email-copy-grades/openapi.json).

- `POST /v1/email-copy-grades` - Grade email or LinkedIn copy (`email-copy-grades.grade`): [/docs/api/email-copy-grades/grade.md](/docs/api/email-copy-grades/grade.md)

## Grade email or LinkedIn copy

`POST /v1/email-copy-grades` - operationId `email-copy-grades.grade`

| Permission | Rate limit |
| --- | --- |
| Campaigns view and the `ask` permission | 20 requests a minute and 500 a day per workspace (Free plan: 2 a minute and 50 a day) |

Grades one step's copy and returns its overall score, its band and a score for each question. Send the text as
`copy`, the kind of step as `channel`, and a `subjectKey` you choose that names the step.

Kenso saves each grade under its `subjectKey` and `channel`. A later call with the same pair returns
the saved grade with `fromSavedGrade` true, even when the copy changed. Send `refresh: true` to grade
the new copy and replace the saved grade. A refresh also needs edit access to Campaigns.

An email is graded on questions scored from 1 to 10, such as `quick_read`, `cta` and `ps`, and on
yes or no questions such as `would_reply` and `weird_word`. Its overall score is the mean of the scored
questions, rounded to one decimal. The band is `keep` at 8 or more when no alarm question got a yes,
`rewrite` at 5 or more, and `start_over` below that. A P.S. that is an AI variable line scores at least
8, because the grader sees only its token.

A LinkedIn step gets five questions scored from 0 to 10: `quick_read`, `cta`, `easy`,
`weird_word` and `personal`. Its overall score is their mean. The band is `keep` at 7.5 or more
when `weird_word` raised no alarm, `rewrite` at 5.5 or more, and `start_over` below that. A
connection note over 300 characters, or a step of 90 words or more, fails `easy`. An AI variable line makes
`personal` at least 8.

Send `campaignId` to grade with that campaign's rubric. A recruiting campaign uses the recruiting rubric and
keeps its grades apart from sales grades. Without it, Kenso uses the sales rubric.

Each call counts toward the workspace's limit of 20 grades a minute and 500 a day, lower on the Free plan. A call
that returns a saved grade counts too.

Errors:

- `400 validation_failed`: `copy` or `subjectKey` is missing or too long, `channel` is not
one of the three channels, or `subjectKey` starts with a reserved prefix.
- `403 permission_denied`: `refresh` is true and the member cannot edit Campaigns.
- `404 not_found`: `campaignId` is not a campaign of this workspace.
- `429 quota_exceeded`: the workspace reached its grade limit. Wait for `Retry-After` seconds.
- `503 service_unavailable`: the grade failed. Try again.
- `504 upstream_timeout`: the grade took too long. Try again.

Requires Campaigns view and the `ask` permission.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/email-copy-grades/POST/v1/email-copy-grades)

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

The copy to grade.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `copy` | string | yes | The step's text to grade. Required, at most 20,000 characters. |
| `subjectKey` | string | yes | A key you choose that names the step, such as a campaign and step id. Kenso saves the grade under this key and `channel`. Required, at most 160 characters on `email`, 140 on `linkedin_connection` and 143 on `linkedin_message` (149, 129 and 132 for a recruiting campaign). It cannot start with `recruiting:`, and an email key cannot start with `linkedin_connection:` or `linkedin_message:`. |
| `refresh` | boolean | no | When true, Kenso grades the copy again and replaces the saved grade. Needs edit access to Campaigns. Defaults to false. |
| `channel` | string | no | The kind of step the copy is for: `email` (the default), `linkedin_connection` or `linkedin_message`. |
| `campaignId` | integer (int64) | no | The campaign the copy is for. A recruiting campaign grades with the recruiting rubric and keeps its own saved grade. Omit it, or send 0, to grade with the sales rubric. |

### Response 200

`data` is a `EmailCopyGrade`.

| Field | Type | Description |
| --- | --- | --- |
| `id` | integer (int64) | The saved grade's id. A regrade replaces the grade under the same id, so `id` with `copyHash` names the current grade of that copy. |
| `channel` | string | The channel that was graded: `email`, `linkedin_connection` or `linkedin_message`. |
| `copyHash` | string | A SHA-256 hash, in hex, of the copy that was graded. |
| `gradedAt` | string (date-time) | When Kenso graded the copy, in UTC. |
| `fromSavedGrade` | boolean | True when Kenso returned the saved grade instead of grading the copy again. |
| `overall` | EmailCopyGradeOverall | The overall score and band. |
| `general` | EmailCopyGradeGeneral | The overall score and band again, under other names. Prefer `overall`. |
| `questions` | array of EmailCopyGradeQuestion | The grade of each question. |
| `criteria` | array of EmailCopyGradeCriterion | The same questions as `questions`, under other field names. Prefer `questions`. |

### Request

```bash
curl -X POST "https://api.ken.so/v1/email-copy-grades" \
  -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 '{
  "copy": "string",
  "subjectKey": "string",
  "refresh": true,
  "channel": "email",
  "campaignId": 812
}'
```

### Example response

```json
{
  "success": true,
  "data": {
    "id": 812,
    "channel": "email",
    "copyHash": "string",
    "gradedAt": "2026-09-23T15:02:11Z",
    "fromSavedGrade": true,
    "overall": {
      "score": 0.5,
      "band": "keep",
      "summary": "Keep",
      "alarmQuestionIds": [
        "string"
      ]
    },
    "general": {
      "score": 0.5,
      "label": "string"
    },
    "questions": [
      {
        "id": "quick_read",
        "label": "string",
        "kind": "score",
        "blurb": "string",
        "alarm": true,
        "score": 1,
        "yes": true,
        "probability": 0.5
      }
    ],
    "criteria": [
      {
        "key": "string",
        "label": "string",
        "kind": "score",
        "summary": "string",
        "score": 1,
        "yes": true,
        "probability": 0.5
      }
    ]
  }
}
```

## Types

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

### EmailCopyGradeOverall

The overall score and band.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `score` | number (double) | no | The mean of the scored questions, rounded to one decimal: 1 to 10 for an email, 0 to 10 for a LinkedIn step. |
| `band` | string | no | What to do with the copy: `keep`, `rewrite` or `start_over`. |
| `summary` | string | no | The band in words: `Keep`, `Rewrite so it is easier` or `Start over`. |
| `alarmQuestionIds` | array of string | no | The ids of the alarm questions that got a yes. Any of them keeps the copy out of `keep`. |

### EmailCopyGradeGeneral

The overall score and band, under other names.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `score` | number (double) | no | The overall score, the same as `overall.score`. |
| `label` | string | no | The band, the same as `overall.band`. |

### EmailCopyGradeQuestion

One question's grade.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | no | The question's id, such as `quick_read` or `weird_word`. |
| `label` | string | no | The question's display name. |
| `kind` | string | no | How the question is answered: `score` or `boolean`. |
| `blurb` | string | no | A short note: what the question checks on an email, or what Kenso found on a LinkedIn step. |
| `alarm` | boolean | no | True for an alarm question: a yes on it keeps the copy out of `keep`. |
| `score` | integer (int32) | no | The question's score on a `score` question. Null on a `boolean` question. |
| `yes` | boolean | no | The yes or no answer on a `boolean` question and on the LinkedIn `weird_word` question. Null otherwise. |
| `probability` | number (double) | no | How likely the answer is yes, from 0 to 1, on a `boolean` question. Null otherwise. |

### EmailCopyGradeCriterion

One question's grade, under other field names.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `key` | string | no | The question's id, the same as the question's `id`. |
| `label` | string | no | The question's display name. |
| `kind` | string | no | How the question is answered: `score` or `boolean`. |
| `summary` | string | no | A short note, the same as the question's `blurb`. |
| `score` | integer (int32) | no | The question's score on a `score` question. Null on a `boolean` question. |
| `yes` | boolean | no | The yes or no answer on a `boolean` question and on the LinkedIn `weird_word` question. Null otherwise. |
| `probability` | number (double) | no | How likely the answer is yes, from 0 to 1, on a `boolean` question. Null otherwise. |

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