> 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-lints/openapi.json](/docs/api/email-copy-lints/openapi.json). CLI docs offline: `kenso docs <topic>`.
> Last updated: 2026-11-22.

# Copy checks: Lint an email step

> **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 [Copy checks](/docs/api/email-copy-lints.md). Authentication, workspaces and errors: [/docs.md](/docs.md).

## Lint an email step

`POST /v1/email-copy-lints` - operationId `email-copy-lints.lint`

| Permission | Rate limit |
| --- | --- |
| Campaigns view | 4,800 requests a minute per API key |

Checks one email step's subject and body against every rule and returns each rule's result, with the text it
matched. Send the step's `stepOrder` so the first email and follow-ups get their own rules.

Each rule is `pass`, `fail` or `skipped`. A failed rule has a severity: `reject` means the
copy should not go out as it is, and `flag` means a person should look at it. `passed` is false when any
rule failed with `reject`. The rules come back in the same order every time.

The lint does not judge whether a claim is true or the offer is clear. For a read of the copy itself, use
`POST /v1/email-copy-grades`.

The rules, which reject unless marked as a flag:

- `subject_length`: the subject has 1 to 60 characters.
- `body_words`: the body has 40 to 180 words.
- `static_words`: the words you wrote, without the greeting, AI variable lines, signature and P.S., number
50 to 80 on the first email and 30 to 60 on a follow-up. Over the range rejects, and under it flags.
- `em_dash`: no em dashes.
- `links`: at most one link, https only, no link shortener, and no web address as the link text.
- `placeholders`: no text in square brackets, and no TODO or TBD.
- `merge_fields`: every `{token}` is one a sequence step accepts, and a custom variable key counts only
when `customVariableKeys` lists it. No `{a|b}` spintax and no `{sender_signature}`.
- `blank_merge_fields` (flag): no contact fields that are often blank.
- `ai_variables`: every `{{AI variable}}` is named in `variables`. Skipped when you omit
`variables`.
- `first_line_fact` (flag), `first_line_first_person`, `first_line_praise`,
`first_line_hedging` and `first_line_length` (flag): on the first email, the opening sentence names a
number, a name or a place, uses no first person (I, me, we, our), holds no praise or hedging, and has 8 to 20
words.
Skipped on a follow-up and when the opener is an AI variable.
- `bridge` (flag): on the first email, the sentence after the opener does not jump to a generic statement.
- `spam_never`: no word from the never tier and no fake Re: or Fwd: subject.
- `spam_high`: one high-tier word flags, and two or more reject.
- `spam_medium`: three or more medium-tier words reject. With `isFinanceVertical`, finance words do not
count.
- `spam_subject`: the subject has no word from any tier, no $ or %, and no stacked numbers.
- `spam_structure`: no word in all caps, at most one ! per email, and no !!! or ???.
- `copy_tells` (flag): no stock phrases or template shapes that readers skim past, such as "hope this finds
you well", "just circling back", "it's not X, it's Y" or "faster, cheaper, and safer". Each match reads
`tell: matched text`. A phrase another rule already failed on is not listed again. It is a check of taste
only, so it never rejects.

Errors:

- `400 validation_failed`: `body` is blank or over 20,000 characters, `subject` is over 1,000
characters, `stepOrder` is outside 1 to 30, or `variables` or `customVariableKeys` lists more
than 100 entries or an entry over 200 characters.

Requires Campaigns view.

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

### 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 step's copy and context.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `subject` | string | no | The step's subject line, at most 1,000 characters. An empty subject fails `subject_length`. |
| `body` | string | yes | The step's body, as plain text or the editor's HTML. Required, at most 20,000 characters. |
| `stepOrder` | integer (int32) | no | The step's place in the sequence, from 1 to 30: 1 (the default) is the first email, and 2 and up are follow-ups. |
| `variables` | array of string | no | The names of the campaign's AI variables that have a personalization prompt, such as `First Line`. Omit it to skip the `ai_variables` rule. At most 100 names of up to 200 characters each. |
| `customVariableKeys` | array of string | no | The campaign's custom variable keys, such as `industry_note`. A `{key}` token passes `merge_fields` only when its key is listed. At most 100 keys of up to 200 characters each. |
| `isFinanceVertical` | boolean | no | True when the sender's business is in finance, insurance, real estate or lending. Then insurance, mortgage, loans, investment and rates do not count toward `spam_medium`. Defaults to false. |

### Response 200

`data` is a `EmailCopyLint`.

| Field | Type | Description |
| --- | --- | --- |
| `passed` | boolean | True when no rule failed with `reject`. |
| `rejectCount` | integer (int32) | How many rules failed with `reject`. |
| `flagCount` | integer (int32) | How many rules failed with `flag`. |
| `wordCount` | integer (int32) | Words in the whole body, from the greeting through the signature and P.S. |
| `staticWordCount` | integer (int32) | The words you wrote, without the greeting, AI variable lines, signature or P.S. |
| `linkCount` | integer (int32) | How many links the body has. |
| `firstLine` | string | The opening sentence the first-line rules read. Null on a follow-up, when there is no opener, or when the opener is an AI variable. |
| `rules` | array of EmailCopyLintRule | Every rule's result, always in the same order. |

### Request

```bash
curl -X POST "https://api.ken.so/v1/email-copy-lints" \
  -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 '{
  "subject": "string",
  "body": "string",
  "stepOrder": 1,
  "variables": [
    "string"
  ],
  "customVariableKeys": [
    "industry_note"
  ],
  "isFinanceVertical": true
}'
```

### Example response

```json
{
  "success": true,
  "data": {
    "passed": true,
    "rejectCount": 1,
    "flagCount": 1,
    "wordCount": 1,
    "staticWordCount": 1,
    "linkCount": 1,
    "firstLine": "string",
    "rules": [
      {
        "rule": "subject_length",
        "status": "pass",
        "severity": "reject",
        "message": "string",
        "matches": [
          "string"
        ]
      }
    ]
  }
}
```

## Types

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

### EmailCopyLintRule

One rule's result.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `rule` | string | no | The rule's id: `subject_length`, `body_words`, `static_words`, `em_dash`, `links`, `placeholders`, `merge_fields`, `blank_merge_fields`, `ai_variables`, `first_line_fact`, `first_line_first_person`, `first_line_praise`, `first_line_hedging`, `first_line_length`, `bridge`, `spam_never`, `spam_high`, `spam_medium`, `spam_subject`, `spam_structure` or `copy_tells`. |
| `status` | string | no | The result: `pass`, `fail` or `skipped`. |
| `severity` | string | no | How serious a failure is: `reject` or `flag`. Null unless the rule failed. |
| `message` | string | no | What the rule found, or why it was skipped, in words. |
| `matches` | array of string | no | The text that broke the rule, at most 20 entries. `spam_medium` lists its words even when it passes, and `copy_tells` lists each match as `tell: matched text`, at most 80 characters of text. Empty when nothing matched. |
