Skip to Content
Copy and personalization

Copy grades

Grade email or LinkedIn copy before you send it.

Copy and personalization1 endpointKen-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.

Grade email or LinkedIn copy

POST/v1/email-copy-gradesemail-copy-grades.grade
Permission
Campaigns view and the ask permission
Rate limit
20 requests a minute and 500 a day per workspace (Free plan: 2 a minute and 50 a day)

Try it on developer.ken.so

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.

Request body

application/json, optional.

The copy to grade.

FieldTypeRequiredDescription
copystringrequiredThe step's text to grade. Required, at most 20,000 characters.
subjectKeystringrequiredA 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:.
refreshbooleanoptionalWhen true, Kenso grades the copy again and replaces the saved grade. Needs edit access to Campaigns. Defaults to false.
channelstringoptionalThe kind of step the copy is for: email (the default), linkedin_connection or linkedin_message.
campaignIdinteger (int64)optionalThe 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.
Request
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
}'

Response 200

data is a EmailCopyGrade.

Show the 9 response fields and an example

The fields and an example are also on this endpoint's Markdown page.


On this page