Kenso MCP tools

Email Copy email_copy

Call it from an MCP client connected to https://mcp.ken.so/mcp: reads go through email_copy_read and changes through email_copy_write. Each takes operation plus that operation's parameters, and your workspace role decides which operations you see.

Each operation with a route calls the Kenso API at https://api.ken.so with Authorization: Bearer <Kenso API key>, Ken-Version: 1.1 and X-Ken-Workspace-Id: <workspace id>. You can call that route directly with the same headers.

Operations: image-variables-create, image-variables-delete, image-variables-estimate, campaign-images-get, image-variables-get, grade, lint, campaign-images-list, deliverability-rules-list, image-variables-list, image-variables-regenerate-contact, image-variables-set-shared-image, image-variables-test, image-variables-update

image-variables-create

Write. Early access: needs campaign_images on for the workspace. POST https://api.ken.so/v1/campaigns/{campaignId}/image-variables

Path: campaignId

Body (json): altText string, enabled boolean, format string, frameCount integer, frameDurationMs integer, key string, kind string, model string, prompt string, quality string, references array, requiredForSending boolean, size string, spellingCheck boolean

Declare one image variable on a campaign. Returns 201 and Location. It starts off. Dark behind campaign_images. Needs a ready link host. Generates nothing and costs nothing.

POST /api/v1/campaigns/{campaignId}/image-variables. Sends Ken-Version 1.1.
key is normalized to snake_case and becomes the {{key}} token. kind is shared (one image for every
lead) or per_prospect (one generated image per lead; prompt required, at most 4000 characters).
references adds lead images to the prompt: profile_photo, company_logo, sender_logo, website_screenshot,
custom_image (shared allows only sender_logo). A shared prompt takes no tokens like {first_name} or
{{company}}: 400 on prompt. model is an image model id from image-variables-list models
(default: openai/gpt-image-2.6-sunburst). size is 1024x1024, 1536x1024 or 1024x1536; quality is low, medium
or high. alt_text is at most 200 characters. Only the fields given are sent.
format is still (default) or gif, an animated GIF: GPT Image 2.6 only (a model whose supportsGif is true in
image-variables-list), no references, frame_count 2-16 (default 9) and frame_duration_ms 20-2000 (default 200,
rounded to 10). A GIF costs more than a still. A gif is refused with 400 while animated GIFs are not available.
A new variable starts off: run image-variables-estimate, then turn it on with
image-variables-update enabled=true.
Fails with 409 link_host_required (no ready link host), image_variable_limit (5 per campaign) or
variable_key_taken (an image, custom or AI variable already uses the key).

image-variables-delete

Write. Early access: needs campaign_images on for the workspace. DELETE https://api.ken.so/v1/campaigns/{campaignId}/image-variables/{variableKey}

Path: campaignId, variableKey

Delete one image variable. Returns 204. Its images stay. Dark behind campaign_images.

DELETE /api/v1/campaigns/{campaignId}/image-variables/{variableKey}. Sends Ken-Version 1.1.
Fails with 409 image_variable_in_use while a sequence step holds the {{key}} token: remove the token
from the steps first, or disable the variable with image-variables-update enabled=false.

image-variables-estimate

Read. Early access: needs campaign_images on for the workspace. POST https://api.ken.so/v1/campaigns/{campaignId}/image-variables/{variableKey}/estimate

Path: campaignId, variableKey

Body (json): format string, frameCount integer, frameDurationMs integer, model string, prompt string, quality string, references array, size string, spellingCheck boolean

Estimate what an image variable costs to run, optionally with an unsaved draft of its settings. Dark behind campaign_images. Generates nothing. Prices are credits.

POST /api/v1/campaigns/{campaignId}/image-variables/{variableKey}/estimate. Sends Ken-Version 1.1.
The draft fields override the saved settings for this estimate only. Returns leadsNow (leads that
would get an image now), replaceCount (current images a changed draft replaces), creditsPerImage,
creditsNow and creditsPerNewLead. A shared variable costs one image. format=gif prices an animated GIF
(GPT Image 2.6 only, no references, frame_count 2-16, frame_duration_ms 20-2000): more frames cost more.

campaign-images-get

Read. Early access: needs campaign_images on for the workspace. GET https://api.ken.so/v1/campaign-images/{imageKey}

Path: imageKey

One campaign image by its key, with a fresh preview URL (1 hour).

GET /api/v1/campaign-images/{imageKey}. Sends Ken-Version 1.1; client_id is sent as X-Ken-Workspace-Id.
image_key is the 26-character imageKey from email_copy(operation="campaign-images-list"). Returns imageKey,
contactId, variableKey, status (pending|ready|failed), errorCode, errorDetail, width, height, previewUrl,
previewExpiresAt (1 hour) and updatedAt. An unknown key is 404. Needs the campaign_images flag (404 while it
is off) and the Campaigns page.

image-variables-get

Read. Early access: needs campaign_images on for the workspace. GET https://api.ken.so/v1/campaigns/{campaignId}/image-variables/{variableKey}

Path: campaignId, variableKey

Get one image variable with its status counts and shared image. Dark behind campaign_images.

GET /api/v1/campaigns/{campaignId}/image-variables/{variableKey}. Sends Ken-Version 1.1.
counts holds ready, pending and failed images. sharedImage is present on a shared variable with an image.

grade

Write. POST https://api.ken.so/v1/email-copy-grades

Body (json): campaignId integer, channel string, copy string, refresh boolean, subjectKey string

Grade sequencer email or LinkedIn copy. A repeat call can return the saved grade. refresh false returns the saved grade for subjectKey. refresh true reruns. 20 a minute, 500 a day per workspace. Use this while writing email or LinkedIn copy.

POST /api/v1/email-copy-grades. Public. Sends Ken-Version 1.1.
The gateway path is /api/v1/email-copy-grades (backend POST /v1/email-copy-grades).
client_id is sent as X-Ken-Workspace-Id. There is no isFollowUp field.

subject_key is the stable id for this step. copy is plain text.
refresh false returns the saved grade for that subjectKey when one exists,
even if copy changed, and does not grade it again. refresh true regrades it and
overwrites the saved grade, so it needs campaigns edit (403 otherwise).
One request per call. Every call, a saved grade included, takes one unit of
the workspace's aiEmailCopyGrades quota (20 a minute, 500 a day): past it,
429 quota_exceeded with Retry-After. Grade the copy once it is written,
not on every keystroke.

channel is email (the default when omitted), linkedin_connection, or
linkedin_message. Any other value fails before the call. Saved grades are
kept per channel, so the same subject_key on two channels is two grades.
The response echoes channel. subject_key is at most 160 characters, 140
on linkedin_connection and 143 on linkedin_message, because the channel
prefixes the saved key. An email subject_key cannot start with
linkedin_connection: or linkedin_message:.

campaign_id is optional: the campaign the copy is for. A recruiting
campaign grades with the recruiting rubric (the same criteria keys,
worded for a candidate) and its saved grades stay apart from sales
grades, so its subject_key is at most 149 characters, 129 on
linkedin_connection and 132 on linkedin_message. Omit it for sales
copy. A subject_key cannot start with recruiting:. A campaign_id from
another workspace is 404.

A follow-up email's copy must start with `This is a follow-up.\n` before
the email text. The tool does not prepend that line.

Email (channel email or omitted):
criteria keys, in order: quick_read, makes_sense, easy, cta, ps,
would_reply, weird_word.
quick_read, makes_sense, cta, and ps scores are integers 1-10.
easy, would_reply, and weird_word scores are probabilities 0-1, and their
summary is Yes or No.

general.label is keep, rewrite, or start_over.
general.score is the mean of quick_read, makes_sense, cta, and ps.
A weird_word Yes cannot be keep.

LinkedIn (channel linkedin_connection or linkedin_message):
criteria keys, in order: quick_read, cta, easy, weird_word, personal.
Every score is an integer 0-10 and summary is a short note.
quick_read is the model's read of the note; summary is the word count.
cta comes from the question marks: none 2, one 10, more than one
8 - 2 per extra question (at least 2).
easy is 3 when a linkedin_connection note is over 300 characters or the
copy is 90 words or more, else 10 when the model says it is easy to answer from a
phone and 5 when not.
weird_word is 10, or 2 when a phrase reads like a template (an alarm).
personal is the model's score; 7 or more mentions something specific to them.
A {{double brace}} AI line scores at least 8, and a concrete detail tied to
the point scores high. A {firstName} or {companyName} merge field alone
scores low, in single or double braces ({{firstName}} gets no floor).
general.score is the mean of the five bars. general.label is keep at 7.5
or more with no weird_word alarm, rewrite at 5.5 or more, else start_over.

Returns the API data object: channel, general (score, label), criteria
(key, label, score, summary), gradedAt, and copyHash.

Examples:
- email_copy(operation="grade", subject_key="campaign:8714:email:1", copy="Subject\n\nBody", client_id=7)
- email_copy(operation="grade", subject_key="campaign:8714:email:2", copy="This is a follow-up.\nSubject\n\nBody", refresh=true, client_id=7)
- email_copy(operation="grade", subject_key="campaign:8714:step:3", copy="Hi {firstName}, {{opener}} Worth a chat?", channel="linkedin_connection", client_id=7)

lint

Read. POST https://api.ken.so/v1/email-copy-lints

Body (json): body string, customVariableKeys array, isFinanceVertical boolean, stepOrder integer, subject string, variables array

Lint one sequencer email against the email-review rules. No model call, no quota. Returns pass, fail (reject or flag) or skipped per rule, with the matched text. The same input always returns the same result. Run it on every draft.

POST /api/v1/email-copy-lints. Public. Sends Ken-Version 1.1.
The gateway path is /api/v1/email-copy-lints (backend POST /v1/email-copy-lints).
client_id is sent as X-Ken-Workspace-Id. Requires campaigns view.

body is the step's body, plain text or the live HTML (the lint reads it as
plain text; required, at most 20,000 characters). subject is the step's
subject (an empty one fails subject_length). step_order is 1 for the first
email (the default) and 2-30 for a follow-up. variables lists each AI
variable that has a personalization prompt
(`prompts(operation="list", campaign_id=..., segment_id=..., flow="personalization")`).
Leave variables out and ai_variables is skipped; pass [] to require a
prompt for every AI variable. custom_variable_keys lists the campaign's
registered custom variable keys (`industry_note`); a {key} merge field
passes only when its key is listed, as on the sequence save. An AI
variable name never clears a single-brace merge field: {first_line} fails
even when variables names "First Line". Set is_finance_vertical for a
client in finance, insurance, real estate or lending: insurance, mortgage,
loans, investment and rates then do not count toward the MEDIUM budget
(the subject stays strict).

Rules, in the order returned (severity when the rule fails):
- subject_length (reject): 1-60 characters.
- body_words (reject): 40-180 words, greeting through signature and PS.
- static_words: prose and CTA without the greeting, AI variable lines,
  signature or PS. Email 1 50-80, a follow-up 30-60. Over is reject (one
  value-stack email per sequence may run to about 100), under is flag.
- em_dash (reject): no em dash.
- links (reject): at most 1 link, the signature link included; https only,
  no shortener, no web address as the link text. An address typed as text
  without https:// (the form a plain text campaign uses: www.example.com/apply)
  is not counted as a link, so keep to one yourself.
- placeholders (reject): no [square bracket], TODO or TBD.
- merge_fields (reject): every {lead variable} is one the sequence save
  accepts (legacy aliases such as {companyName} fail), no {a|b} spintax, no
  malformed {spin:...}, no {sender_signature}. Keys in
  custom_variable_keys pass.
- blank_merge_fields (flag): {fullName}, {industry}, {location}, {headline}
  and the other fields most contacts lack.
- ai_variables (reject): every {{AI variable}} in subject or body is named
  in variables. Skipped when variables is omitted.
- first_line_fact (flag), first_line_first_person, first_line_praise,
  first_line_hedging (reject), first_line_length (flag, 8-20 words): the
  static opener of email 1. Skipped on a follow-up and when the opener is
  an AI variable (check its rendered samples instead). first_line_fact
  looks for a number, a name or a place; it cannot tell whether the fact
  is true.
- bridge (flag): the sentence after the opener does not jump to a generic
  statement ("Scaling a SaaS company...", "Most teams..."). Email 1 only.
- spam_never (reject): a NEVER-tier word ("free", "credit card", phishing
  and scam phrases) or a fake Re:/Fwd: subject on email 1.
- spam_high: one HIGH-tier word is flag, two or more reject.
- spam_medium: three or more MEDIUM-tier words reject; the words are listed
  even when it passes. is_finance_vertical leaves the finance vocabulary
  out of the count.
- spam_subject (reject): any tiered word, $, % or two numbers in the subject.
- spam_structure (reject): an ALL CAPS word, more than one !, !!! or ???.

passed is false when any rule failed at reject. A rule cannot judge truth,
the offer, the CTA or the voice: read those yourself, and for a model's
second opinion use email_copy(operation="grade", ...).

Returns the API data object: passed, rejectCount, flagCount, wordCount,
staticWordCount, linkCount, firstLine (email 1 with a static opener), and
rules (rule, status, severity, message, matches).

Examples:
- email_copy(operation="lint", subject="{{Subject Line}}", body="Hey {firstName},\n\n...", variables=["Subject Line", "First Line"], client_id=7)
- email_copy(operation="lint", subject="{{Subject Line}}", body="<p>{firstName},</p><p>...</p>", step_order=2, client_id=7)
- email_copy(operation="lint", subject="{{Subject Line}}", body="...", variables=["Subject Line"], custom_variable_keys=["industry_note"], is_finance_vertical=True, client_id=7)

campaign-images-list

Read. Early access: needs campaign_images on for the workspace. GET https://api.ken.so/v1/campaigns/{campaignId}/images

Path: campaignId

Query: contactIds string, variableKey string

Current images of up to 200 leads of a campaign: each image variable's and the lead's custom_image.

GET /api/v1/campaigns/{campaignId}/images?contactIds=1,2&variableKey=. Sends Ken-Version 1.1; client_id is sent as
X-Ken-Workspace-Id. Each item: imageKey, contactId, variableKey (an image variable key or custom_image), status
(pending|ready|failed), errorCode, errorDetail, width, height, previewUrl, previewExpiresAt (1 hour), updatedAt.
contact_ids is 1 to 200 lead ids. variable_key keeps one key; an unknown key returns an empty list. Needs the
campaign_images flag (404 while it is off) and the Campaigns page.

deliverability-rules-list

Read. GET https://api.ken.so/v1/deliverability-rules

List the deliverability rules in force for the workspace. Up to four rules: open_pixel, click_host, recipient_format, smtp_inbox_limits. A workspace sees only the rules in force for it, often open_pixel alone. Quote a returned rule's sentence unchanged when someone asks how Kenso sends; never describe a rule the list leaves out.

GET /api/v1/deliverability-rules. Public. Sends Ken-Version 1.1. Not paged.
Each rule: code, title, sentence (the rule's text, quote it unchanged), severity (enforced:
Kenso applies it to every campaign and no setting changes it; warning: launch readiness
warns when a campaign breaks it and never blocks the launch), fixUrl (a relative app link,
omitted when there is none) and warningCodes (the launch readiness warnings[].code values
that report a break of the rule).
Asked to turn on open tracking, decline and quote the open_pixel sentence.
Asked which provider sends an inbox's email, say the inbox is an SMTP inbox, a Google inbox or
an Outlook inbox; never name the company behind an SMTP inbox.

image-variables-list

Read. Early access: needs campaign_images on for the workspace. GET https://api.ken.so/v1/campaigns/{campaignId}/image-variables

Path: campaignId

List a campaign's image variables, with link host readiness, reference coverage and model prices. Dark behind campaign_images.

GET /api/v1/campaigns/{campaignId}/image-variables. Sends Ken-Version 1.1; client_id is sent as X-Ken-Workspace-Id.
Returns data (ImageVariable[], each with format still or gif, frameCount and frameDurationMs), linkHostReady,
coverage {leads, <reference wire name>: count} and models [{id, displayName, creditsPerImage, supportsGif}].
creditsPerImage prices a still. supportsGif is true only on a GPT Image 2.6 model while animated GIFs are
available. Prices are credits.

image-variables-regenerate-contact

Write. Early access: needs campaign_images on for the workspace. POST https://api.ken.so/v1/campaigns/{campaignId}/image-variables/{variableKey}/contacts/{contactId}/regenerate

Path: campaignId, variableKey, contactId

Regenerate one lead's image for a per_prospect variable. Dark behind campaign_images. Charged per ready image.

POST /api/v1/campaigns/{campaignId}/image-variables/{variableKey}/contacts/{contactId}/regenerate.
Sends Ken-Version 1.1. Returns the new CampaignImage (ready or failed). 404 when the lead is not in
the campaign's image audience. 409 image_in_use when the lead already has a sent or queued step that
uses the image, blocked when Kenso staff blocked the lead's current image (a changed prompt lets the
generation job make a new one), wrong_kind on a shared variable. Counts 1 against the image editor quota.

image-variables-set-shared-image

Write. Early access: needs campaign_images on for the workspace. POST https://api.ken.so/v1/campaigns/{campaignId}/image-variables/{variableKey}/shared-image

Path: campaignId, variableKey

Set a shared variable's image from a URL, or generate it from its prompt. Exactly one. Dark behind campaign_images. Generating is charged.

POST /api/v1/campaigns/{campaignId}/image-variables/{variableKey}/shared-image. Sends Ken-Version 1.1.
Pass url (an https image Ken fetches and stores) or generate=true, never both. Returns the variable
with its sharedImage. 409 wrong_kind on a per_prospect variable, link_host_required without a ready
link host, blocked when Kenso staff blocked the current shared image (no source replaces it). A
generate counts 1 against the image editor quota.

image-variables-test

Write. Early access: needs campaign_images on for the workspace. POST https://api.ken.so/v1/campaigns/{campaignId}/image-variables/{variableKey}/test

Path: campaignId, variableKey

Generate a per_prospect variable's image for up to 5 leads and return them. Dark behind campaign_images. Synchronous; charged per ready image.

POST /api/v1/campaigns/{campaignId}/image-variables/{variableKey}/test. Sends Ken-Version 1.1.
Picks leads with no current image first, then leads whose image failed; never a lead whose image
Kenso staff blocked. Returns data.images
(CampaignImage[]: contactId, status ready or failed, previewUrl). Can take minutes. Counts one per
lead it picks (at most 5, none when no lead is eligible) against the workspace's image editor quota
(429 quota_exceeded when spent); a 404 or 409 counts nothing. 409 wrong_kind on a shared variable.

image-variables-update

Write. Early access: needs campaign_images on for the workspace. PATCH https://api.ken.so/v1/campaigns/{campaignId}/image-variables/{variableKey}

Path: campaignId, variableKey

Body (json): altText string, enabled boolean, format string, frameCount integer, frameDurationMs integer, key string, kind string, model string, prompt string, quality string, references array, requiredForSending boolean, size string, spellingCheck boolean

Update one image variable. Absent fields stay unchanged; the key and kind cannot change. Dark behind campaign_images.

PATCH /api/v1/campaigns/{campaignId}/image-variables/{variableKey}. Sends Ken-Version 1.1.
Same fields and rules as image-variables-create. An empty alt_text or prompt clears it.
enabled=true turns the variable on (a new variable starts off); run image-variables-estimate first.
enabled=false stops new images and is always allowed. A changed prompt, references, model, size,
quality, format or GIF frames marks the existing per-lead images for replacement; run
image-variables-estimate first to see the cost.
format=still clears frame_count and frame_duration_ms. format=gif (GPT Image 2.6 only, no references,
frame_count 2-16, frame_duration_ms 20-2000) takes 9 frames at 200 ms unless given. A GIF variable cannot
move to a model without GIF support: set format=still first.