Markets markets
Kenso's market packs: how to write cold email in each language and country (formality, salutations, sign-offs, style, banned phrases) and each country's cold email rules, a campaign's steps written in each language it enables, and the consent-first countries a campaign must acknowledge before launch. Not stock or financial markets.
Call it from an MCP client connected to https://mcp.ken.so/mcp: reads go through markets_read and changes through markets_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: compliance-acknowledge, localizations-approve, localizations-generate, compliance-get, languages-get, get, billing-plans-list, localizations-list, list, localizations-regenerate, localizations-update
compliance-acknowledge
Write. Early access: needs multilingual_outreach on for the workspace. POST https://api.ken.so/v1/campaigns/{campaignId}/compliance/acknowledgements
Path: campaignId
Body (json): countries array
Acknowledge the cold email rules of a campaign's consent-first countries, so launch can proceed.
POST /api/v1/campaigns/{campaignId}/compliance/acknowledgements with {"countries": ["ES"]}. Needs the
multilingual_outreach flag (404 while it is off) and campaign edit. Sends Ken-Version 1.1.
countries: ISO-2 codes of countries markets(operation="compliance-get") lists for the campaign. Records the
caller and the time for each, which lets campaigns(operation="launch") proceed for that country. Acknowledge only
after the user has read each country's note and agreed: the acknowledgement is theirs, and it goes on the
workspace's audit log. A country already acknowledged keeps its first acknowledgement, so a repeat is harmless.
Returns the same shape as compliance-get.
Errors (400 validation_failed, details[].code, field countries[i]): required (no country), unknown_country (not
an ISO-2 code Kenso knows), not_required (the campaign has no contacts there, or its rules need no
acknowledgement). Any error records nothing. A campaign in another workspace is 404.
Examples:
- markets(operation="compliance-acknowledge", campaign_id=812, countries=["ES"], client_id=7)
- markets(operation="compliance-acknowledge", campaign_id=812, countries=["ES", "DE"], client_id=7)
localizations-approve
Write. Early access: needs multilingual_outreach on for the workspace. POST https://api.ken.so/v1/campaigns/{campaignId}/localizations/{localizationId}/approve
Path: campaignId, localizationId
Query: channel string
Approve one localized step of a campaign for sending; returns the localization.
POST /api/v1/campaigns/{campaignId}/localizations/{localizationId}/approve. Needs the multilingual_outreach flag
(404 while it is off) and campaign edit. Sends Ken-Version 1.1.
localization_id is the id from markets(operation="localizations-list"). channel (email or linkedin) is needed
only when an email and a LinkedIn localization of the campaign share that id (400 channel_required otherwise).
Only a current draft that passed its quality check is approved: qaReport.passed is true and qaScore reached the
market pack's threshold (a localization a person edited is approved on the rules alone). Records the caller as
approvedByUserId (none for an API key with no user) and approvedAt.
Errors: 409 localization_not_approvable with details[].code not_draft, stale (written from older step text or an
older market pack: run localizations-generate or localizations-regenerate), qa_failed or score_below_threshold;
409 localization_generating while the localization job has it queued; 404 for an id the campaign does not have.
Examples:
- markets(operation="localizations-approve", campaign_id=812, localization_id=5003, client_id=7)
- markets(operation="localizations-approve", campaign_id=812, localization_id=12, channel="linkedin", client_id=7)
localizations-generate
Write. Early access: needs multilingual_outreach on for the workspace. POST https://api.ken.so/v1/campaigns/{campaignId}/localizations
Path: campaignId
Body (json): channel string, languages array, stepIds array
Queue the writing of a campaign's steps in the languages it enables; returns every localization of the campaign.
POST /api/v1/campaigns/{campaignId}/localizations with {"languages": [...], "stepIds": [...], "channel": ...}. Needs the
multilingual_outreach flag (404 while it is off) and campaign edit. Sends Ken-Version 1.1. Answers 202.
languages, step_ids and channel are optional: absent or empty means every language the campaign enables (its
enabledLanguages) and every active email or LinkedIn step with text (not a Studio step, not an AI connection
note). channel (email or linkedin) keeps one channel's steps; an email and a LinkedIn step can share an id, and
channel picks one. A missing localization is created as a draft; a stale, failed or needs_review one, and one written from
older step text or an older market pack, is queued again. A current draft or approved localization, and one
already queued, stay as they are. A localization a person edited (editedByHuman) is queued again only when
step_ids names its step. Nothing is written here: the localization job writes the queued rows
(generating true until it does), so call markets(operation="localizations-list") later to read them.
Errors (400 validation_failed, details[].code): language_not_enabled (the campaign does not enable that
language), no_enabled_languages (the campaign enables none: set enabledLanguages first),
unsupported_language (no market pack for it), step_not_localizable (not an active step of the campaign with
text), invalid_value on field channel. A campaign in another workspace is 404. While the localization job is not on for the workspace,
nothing is queued: 409 invalid_state with details[].code localization_disabled.
Examples:
- markets(operation="localizations-generate", campaign_id=812, client_id=7)
- markets(operation="localizations-generate", campaign_id=812, languages=["fr-FR"], step_ids=[11, 12], client_id=7)
- markets(operation="localizations-generate", campaign_id=812, step_ids=[11], channel="linkedin", client_id=7)
compliance-get
Read. Early access: needs multilingual_outreach on for the workspace. GET https://api.ken.so/v1/campaigns/{campaignId}/compliance
Path: campaignId
Read a campaign's consent-first countries: each country's cold email rule, contact count and acknowledgement.
GET /api/v1/campaigns/{campaignId}/compliance. Needs the multilingual_outreach flag (404 while it is off) and
campaign view. Sends Ken-Version 1.1.
Returns data {acknowledgementRequired, countries[]}. countries lists each country the campaign's live contacts sit
in whose cold email rules launch asks someone to acknowledge (Spain, Germany, ...), most contacts first: iso2 (ES),
name, regime (opt_out, consent or unresolved), note (a short summary of the rule; not legal advice), sources
(public pages), contactCount, and acknowledgedAt and acknowledgedByUserId once someone acknowledged it (absent
before). acknowledgementRequired is true while any listed country has no acknowledgement: launch then answers
409 acknowledgement_required, and launch readiness lists acknowledgement_required. Show the user each note, then
record their agreement with markets(operation="compliance-acknowledge"). A campaign in another workspace is 404.
Examples:
- markets(operation="compliance-get", campaign_id=812, client_id=7)
languages-get
Read. Early access: needs multilingual_outreach on for the workspace. GET https://api.ken.so/v1/campaigns/{campaignId}/languages
Path: campaignId
Read a campaign's languages: its language settings, the market packs it can enable and its contacts per language.
GET /api/v1/campaigns/{campaignId}/languages. Needs the multilingual_outreach flag (404 while it is off) and
campaign view. Sends Ken-Version 1.1.
Returns data {sourceLanguage, languageMode, enabledLanguages, formalityOverrides, languageFallback, available,
mix, unresolved}:
- sourceLanguage (en, or a locale such as fr-FR), languageMode (source_only or auto), enabledLanguages (locales
such as fr-FR), formalityOverrides (locale to formal or informal), languageFallback (source or hold): the
campaign's settings, as campaigns(operation="get") returns them; change them with campaigns(operation="update").
- available: every market pack the campaign can enable, by locale: {locale, name (in its own language), status}
with status supported or tested. Draft packs are left out.
- mix: the campaign's contacts that can still be contacted (live, not do-not-contact) per outreach language, most
contacts first: {locale, contacts, lowConfidence}. lowConfidence of a locale's contacts are under the routing
confidence floor and get the source language.
- unresolved: contacts with no outreach language yet.
A campaign in another workspace is 404.
Examples:
- markets(operation="languages-get", campaign_id=812, client_id=7)
get
Read. GET https://api.ken.so/v1/markets/{locale}
Path: locale
Get one market pack with the cold email notes of its countries. Returns { pack, countries, status }. An unknown locale returns a not-found error.
locale is a pack locale such as fr-FR or es-ES, any case (FR-fr reads as fr-FR).
markets(operation="list") lists the locales there are.
pack is markets/<locale>.json as written: language, formality, salutations,
signOffs, style, bannedPhrases, spamPhrases, examples and the rest.
countries are the countries whose official language this pack writes, each as
markets/countries.json has it: iso2, name, languages (code, locale, share,
official) and coldEmail (regime opt_out, consent or unresolved, note, sources,
requiresAcknowledgement). Every note ends with "Not legal advice."
status is "tested" (passed the quality check) or "supported". A draft pack is
not served: its locale returns the not-found error, and so does a bare language
such as fr.
GET /api/v1/markets/{locale}. Public. Sends Ken-Version 1.1.
billing-plans-list
Read. GET https://api.ken.so/v1/billing/plans
List the plans a new workspace can pick: free, platform, performance.
GET /api/v1/billing/plans. Sends Ken-Version 1.1. Static, so it needs no workspace (X-Ken-Workspace-Id is sent only when one is given or pinned). Returns creditUsdCents (one credit in US cents), freeSignupCredits and plans, in the order free, platform, performance. Each plan has id, name, tagline, includes (bullet copy), canSend (false for free: a new Free workspace cannot send until it picks a plan) and salesLed (true for performance). Platform adds includedCredits, includedCreditsUsdCents and prices (monthly, plus quarterly and annual when configured; each has usdCents, currency, interval and perMonthUsdCents), read from Stripe and left out when Stripe cannot be read. Performance adds bookingUrl. To buy Platform, start a checkout with billing(operation="checkout-sessions-create").
localizations-list
Read. Early access: needs multilingual_outreach on for the workspace. GET https://api.ken.so/v1/campaigns/{campaignId}/localizations
Path: campaignId
Query: channel string, language string, stepId integer
List a campaign's steps in each language: the localized text, its English mirror, score and status.
GET /api/v1/campaigns/{campaignId}/localizations. Needs the multilingual_outreach flag (404 while it is off)
and campaign view. Sends Ken-Version 1.1.
One item per live email or LinkedIn step and language, email first, then by step order, variant and language:
id, channel (email or linkedin), stepId, stepOrder, variant (a to d), language (fr-FR), subjectLine (email only),
bodyContent, status, generating, sourceHash, stale, packVersion, mirrorLanguage (en), mirrorSubject, mirrorBody,
qaScore (0 to 100), qaReport {passed, errors[{code, message}]} (a judge finding has code judge), editedByHuman,
approvedByUserId, approvedAt, lastError, modifiedAt.
status is draft, approved, stale, needs_review or failed. stale is true when the row is marked stale, or was
written from older step text or an older market pack: run localizations-generate again. generating is true while
the localization job has the row queued. One page: pagination.hasMore is always false.
language keeps one locale (any casing). step_id keeps the rows of the email or LinkedIn step with that id.
channel (email or linkedin) keeps one channel's rows; an email and a LinkedIn step can share an id, and channel
picks one. A campaign in another workspace is 404.
Examples:
- markets(operation="localizations-list", campaign_id=812, client_id=7)
- markets(operation="localizations-list", campaign_id=812, language="fr-FR", client_id=7)
list
Read. GET https://api.ken.so/v1/markets
Query: cursor string, limit integer
List every market pack: locale, language, status and countries. Returns { markets: [{ locale, language, status, countries: [iso2] }] }, sorted by locale.
status is "tested" (passed the quality check) or "supported"; draft packs are not listed. countries are the ISO-2 codes of the countries one of whose official languages this pack writes: the pack of that exact locale, else the language's primary pack (Belgium's French reads fr-FR until an fr-BE pack exists). markets(operation="get", locale=...) returns one pack with each country's cold email notes. GET /api/v1/markets. Public. Sends Ken-Version 1.1. The tool follows the cursor and returns every market at once.
localizations-regenerate
Write. Early access: needs multilingual_outreach on for the workspace. POST https://api.ken.so/v1/campaigns/{campaignId}/localizations/{localizationId}/regenerate
Path: campaignId, localizationId
Query: channel string
Body (json): instruction string
Queue one localized step to be written again, with an optional instruction; returns the localization.
POST /api/v1/campaigns/{campaignId}/localizations/{localizationId}/regenerate with {"instruction": ...}. Needs the
multilingual_outreach flag (404 while it is off) and campaign edit. Sends Ken-Version 1.1. Answers 202.
instruction (optional, up to 2,000 characters) says what to change, such as "Shorter, and less formal."; the
localization job rewrites the current text with it, or writes it anew without one. The localization becomes a
draft (an approval is withdrawn, so a live campaign stops sending it: its contacts are held or get the source
text, as the campaign's language fallback says, until it is approved again), and generating is true until the job
has written it: call
markets(operation="localizations-list") later to read it. This rewrites text a person edited. channel as for
localizations-approve.
Errors: 409 localization_generating while the job has it queued; 400 validation_failed with details[].code
language_not_enabled (the campaign no longer enables that language), step_not_localizable (the step has no text to
localize) or too_long (instruction); 409 invalid_state with details[].code localization_disabled while the
localization job is not on for the workspace; 404 for an id the campaign does not have.
Examples:
- markets(operation="localizations-regenerate", campaign_id=812, localization_id=5003, instruction="Shorter.", client_id=7)
localizations-update
Write. Early access: needs multilingual_outreach on for the workspace. PATCH https://api.ken.so/v1/campaigns/{campaignId}/localizations/{localizationId}
Path: campaignId, localizationId
Query: channel string
Body (json): bodyContent string, subjectLine string
Replace the text of one localized step with your own; returns the localization with its rule check.
PATCH /api/v1/campaigns/{campaignId}/localizations/{localizationId} with {"subjectLine": ..., "bodyContent": ...}.
Needs the multilingual_outreach flag (404 while it is off) and campaign edit. Sends Ken-Version 1.1.
Send subject_line, body_content or both; an absent one keeps the stored text, and a LinkedIn localization has no
subject. The text is stored as sent (the unsubscribe link text is set to the market pack's) and checked by the
rules with no model call: qaReport holds their result. editedByHuman becomes true and the localization a draft
(an approval is withdrawn, so a live campaign stops sending it until it is approved again, as for
localizations-regenerate); mirrorSubject, mirrorBody and qaScore stay as they were, for the text before the
edit. An edited draft whose rules pass can be approved with markets(operation="localizations-approve").
channel as for localizations-approve.
Errors: 400 validation_failed for a blank body, a blank subject for a step that has one, or a subject on a
LinkedIn localization, and, while campaign images are on for the workspace, for an email text with image tokens
a sequence save would refuse (more than two, one in the subject or in a handwritten letter, or one not on its own
line or in its own paragraph; the message is the sequence save's, nothing is stored); 409 localization_generating
while the localization job has it queued; 404 for an id the campaign does not have.
Examples:
- markets(operation="localizations-update", campaign_id=812, localization_id=5003, body_content="<p>Bonjour {firstName},</p>...", client_id=7)