Sending Providers sending_providers
Send campaign mail through a provider's HTTP API (Resend, Agentmail, ...): connect a key, add sending addresses as inboxes, recheck the key and domains. The video-provider-connections-* operations connect the workspace's Sendspark, HeyGen or Vidyard account for campaign videos (early access).
Call it from an MCP client connected to https://mcp.ken.so/mcp: reads go through sending_providers_read and changes through sending_providers_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: create, video-provider-connections-create, create-identity, delete, video-provider-connections-delete, get, video-provider-connections-get, list, providers-list, video-provider-connections-list, video-provider-connections-list-library, video-provider-connections-list-sources, update, video-provider-connections-update, verify, video-provider-connections-verify
create
Write. POST https://api.ken.so/v1/sending-provider-connections
Body (json): allowedDomains array, apiKey string, dailyCap integer, inboundMode string, projectId string, provider string, rampEnabled boolean, replyToInboxId integer
Connect a sending provider with the workspace's own API key.
POST /api/v1/sending-provider-connections. Needs the sending_providers flag and the integrations feature (Admin).
Sends Ken-Version 1.1. provider is a slug from sending_providers(operation="providers-list") with kind http_adapter.
Kenso checks the key with one provider call, reads the domains it can send from, registers a webhook for delivery
events, and stores the key encrypted; the key is never returned (keySuffix is its last four characters).
inbound_mode: provider (the provider receives replies; picked when one of its domains receives there) or
reply_to_inbox (Reply-To names reply_to_inbox_id, a connected workspace inbox Kenso reads; it may not be a member's
own mailbox; only a campaign's own Reply-To comes before it). The Reply-To inbox becomes receive-only (role
replies: out of campaign pools and warmup, still read) unless a campaign that can still send has it in its pool;
then it stays a sender and the answer carries the warning reply_to_inbox_sends:{campaign count}.
daily_cap 1 to 100000 (default: the provider's). ramp_enabled (default true) grows the cap over the
first weeks. allowed_domains is staff-only (403 detail staff_only). A provider whose terms forbid cold outreach on
your own key adds a warning. One connection per provider. 400 validation_failed with detail key_rejected,
invalid_key_format, provider_unknown, provider_not_enabled, provider_retired (the provider takes no new connections,
for staff too; nothing is stored), invalid_inbound_mode, invalid_daily_cap, invalid_domain, reply_to_inbox_required,
project_unsupported (no provider that takes new connections uses project_id) or key_scope_missing (the key may not
read the provider's domains);
409 conflict
detail already_connected; 503 detail key_check_inconclusive or provider_unavailable when the provider does not
answer. Returns the connection (fields of get). Next: create-identity for each sending address.
video-provider-connections-create
Write. POST https://api.ken.so/v1/video-provider-connections
Body (json): accountLabel string, apiKey string, apiSecret string, endpointUrl string, provider string, sendsparkWorkspaceId string
Connect the workspace's own Sendspark, HeyGen or Vidyard account for campaign videos.
POST /api/v1/video-provider-connections. Needs the campaigns page and the integrations feature (workspace Admin).
Sends Ken-Version 1.1. provider: sendspark, heygen or vidyard. credentials is one object:
- sendspark: {"api_key", "api_secret", "workspace_id"} (the Sendspark workspace id, 1 to 64 letters, digits, _ or -)
- heygen: {"api_key"}
- vidyard: {"api_key" (the API token), "endpoint_url" (the video agent's https endpoint URL on vidyard.com)}
Kenso checks the credentials with the provider, stores them encrypted as the workspace's key and never returns
them; this tool redacts them from any result or error. HeyGen gets Kenso's webhook registered (a failed
registration still connects, with status error). Sendspark answers webhook.url to paste into its settings (this
tool returns it as [redacted], copy it in Kenso or from the API) and stays unverified until its first event,
Vidyard until its first video. account_label: up to 200 characters, default the provider account's name.
Nothing is stored on a failure. 400 validation_failed detail provider_unknown, invalid_credentials (wrong shape,
or the provider refused the key), invalid_account_label or provider_not_supported; 409 conflict detail
already_connected or key_busy; 503 provider_unavailable (retry after Retry-After). Early access: 404 not_found
until the workspace has the campaign_videos flag, and 403 detail feature_disabled while the provider's own flag
(video_sendspark, video_heygen, video_vidyard) is off. Returns the connection (fields of
video-provider-connections-get).
create-identity
Write. POST https://api.ken.so/v1/sending-provider-connections/{connectionId}/identities
Path: connectionId
Body (json): displayName string, email string, signature string
Add a sending address on a sending provider connection; it becomes a workspace inbox.
POST /api/v1/sending-provider-connections/{connectionId}/identities. Needs the sending_providers flag and the
delivery page (edit). Sends Ken-Version 1.1. The connection must be connected and the address's domain in its
verifiedDomains; a provider whose sendsFromProviderInboxes is true (Agentmail)
instead needs an inbox or sender profile with this address on the provider. With inbound_mode provider, the
domain must be in inboundDomains unless the connection has a Reply-To inbox. Returns 201 with the inbox (the
fields of inboxes(operation="get"), sendingProvider set to the provider slug when the connection is the workspace's own account); add it to campaigns like any inbox.
400 validation_failed detail invalid_email, invalid_display_name, domain_not_verified, address_not_at_provider,
connection_not_connected, identity_has_no_ingest_path or provider_retired (the connection's provider takes no new
identities; its existing inboxes keep sending); 409 conflict detail address_in_use when another workspace
or a live inbox has the address; 404 not_found for a connection outside the workspace.
delete
Write. DELETE https://api.ken.so/v1/sending-provider-connections/{connectionId}
Path: connectionId
Disconnect a sending provider: delete its webhook, its stored key and the connection.
DELETE /api/v1/sending-provider-connections/{connectionId}. Needs the sending_providers flag and the integrations
feature (Admin). Sends Ken-Version 1.1. Removes the provider webhook (best effort), the stored key and the
connection, and clears its campaign holds; answers 204 with no body. Its identities stop sending.
An SMTP preset connection signs out each inbox's SMTP login instead.
409 conflict detail key_busy while the key is in use; 404 not_found for a connection outside the workspace.
video-provider-connections-delete
Write. DELETE https://api.ken.so/v1/video-provider-connections/{connectionId}
Path: connectionId
Disconnect a campaign video provider account: its webhook, stored key and the connection.
DELETE /api/v1/video-provider-connections/{connectionId}. Needs the campaigns page and the integrations feature
(workspace Admin). Sends Ken-Version 1.1. Removes Kenso's HeyGen webhook (best effort), deletes the stored key and
webhook secret, then the connection, and answers 204 with no body. Works while the provider's own flag is off.
409 key_busy while another change to the key is in progress (nothing is deleted then); 404 not_found for a
connection outside the workspace. Early access: 404 not_found until the workspace has the campaign_videos flag.
get
Read. GET https://api.ken.so/v1/sending-provider-connections/{connectionId}
Path: connectionId
Read one sending provider connection.
GET /api/v1/sending-provider-connections/{connectionId}. Needs the sending_providers flag and the delivery page
(view). Sends Ken-Version 1.1. Returns {id, provider, kind (byok: the workspace's own key; managed: Kenso's account),
status (connected, error), inboundMode (provider, reply_to_inbox), replyToInboxId, dailyCap, rampEnabled,
verifiedDomains (domains the provider lets the key send from), inboundDomains (domains whose replies the provider
receives), allowedDomains, keySuffix (last four characters; staff only on a managed connection), projectId (the
project the connection builds and sends in; absent on a provider without projects), webhookUrl, lastVerifiedAt, lastError, warnings, identities (inbox ids), policyRefusals24h (sends the provider refused for
policy in the last 24 hours), heldCampaignCount (campaigns paused on this connection after a refusal), createdAt}.
404 not_found for a connection outside the workspace.
video-provider-connections-get
Read. GET https://api.ken.so/v1/video-provider-connections/{connectionId}
Path: connectionId
Read one campaign video provider connection.
GET /api/v1/video-provider-connections/{connectionId}. Needs the campaigns page (view). Sends Ken-Version 1.1.
Returns {id, provider (sendspark, heygen, vidyard), status (unverified until the first provider event for Sendspark
and Vidyard, connected, error), accountLabel, lastVerifiedAt, lastError (a plain sentence saying what to do),
lastEventAt, webhook {setup (registered_at_connect for HeyGen, pasted_in_provider_ui for Sendspark,
passed_per_submit for Vidyard), url}, createdAt, updatedAt}. webhook.url is Sendspark's URL to paste into its
settings; its last segment is the webhook's credential, so this tool returns it as [redacted]: copy it in Kenso or
from the API. 404 not_found for a connection outside the workspace. Works while the provider's own flag is off.
Early access: 404 not_found until the workspace has the campaign_videos flag.
list
Read. GET https://api.ken.so/v1/sending-provider-connections
List the workspace's sending provider connections.
GET /api/v1/sending-provider-connections. Needs the sending_providers flag and the delivery page (view). Sends Ken-Version 1.1. Returns every connection (no paging) with the fields of get. The key is never returned.
providers-list
Read. GET https://api.ken.so/v1/sending-providers
List the sending providers a workspace can connect.
GET /api/v1/sending-providers. Needs the sending_providers flag and the delivery page (view). Sends Ken-Version 1.1. Returns the providers Kenso has turned on (no paging): slug, displayName, kind (http_adapter connects with an API key; smtp_preset is a mailbox host Kenso fills in for an SMTP inbox), preset (smtp and imap hosts and ports for a preset, its form hints, and usernameIsAddress: true when the username may be left blank because the provider logs in with the mailbox address), defaultDailyCap, supportsProviderInbound (the provider receives replies), supportsFeedbackWebhook, termsForbidOutreach (the provider's terms forbid cold outreach on your own key), sendsFromProviderInboxes (an identity must be an inbox, agent or sender profile the provider account already has, not any address on a verified domain), buildsMessagesNatively (the provider sends only emails built in it ahead of time, with each lead's values as variables), docsUrl. A provider that takes no new connections is not listed. Next: sending_providers(operation="create", provider=slug, api_key=...).
video-provider-connections-list
Read. GET https://api.ken.so/v1/video-provider-connections
List the workspace's campaign video provider connections (Sendspark, HeyGen, Vidyard).
GET /api/v1/video-provider-connections. Needs the campaigns page (view). Sends Ken-Version 1.1. Every connection that was not disconnected, oldest first, not paginated, with the fields of video-provider-connections-get. A connection stays listed while its provider's flag is off, so it can still be removed. Early access: 404 not_found until the workspace has the campaign_videos flag. The credentials are never returned.
video-provider-connections-list-library
Read. GET https://api.ken.so/v1/video-provider-connections/{connectionId}/library
Path: connectionId
List the finished videos in a connected account's library.
GET /api/v1/video-provider-connections/{connectionId}/library. Needs the campaigns page (view). Sends Ken-Version
1.1. Read live from the provider with the stored key, not paginated: each {providerVideoId, title, createdAt}.
Pick one for a shared video with tracking_links(operation="video-variables-create", library_connection_id=...,
provider_video_id=...) (HeyGen only). 400 detail not_supported when the provider has no such list (paste a share
link instead), invalid_credentials when it refused the key (the connection turns error), provider_rejected or
provider_not_supported; 503 provider_unavailable (retry after Retry-After). Early access: 404 not_found until the
workspace has the campaign_videos flag, and 403 detail feature_disabled while the provider's own flag is off.
video-provider-connections-list-sources
Read. GET https://api.ken.so/v1/video-provider-connections/{connectionId}/sources
Path: connectionId
List the templates, dynamic campaigns or video agents a connected account generates lead videos from.
GET /api/v1/video-provider-connections/{connectionId}/sources. Needs the campaigns page (view). Sends Ken-Version
1.1. Read live from the provider with the stored key, not paginated: each {id, name, variables (the
personalization variables it takes)}. Use an id as the source reference in
tracking_links(operation="video-settings-replace"). 400 detail not_supported when the provider has no such list
(enter the reference by hand), invalid_credentials when it refused the key (the connection turns error),
provider_rejected or provider_not_supported; 503 provider_unavailable (retry after Retry-After). Early access: 404
not_found until the workspace has the campaign_videos flag, and 403 detail feature_disabled while the provider's
own flag is off.
update
Write. PATCH https://api.ken.so/v1/sending-provider-connections/{connectionId}
Path: connectionId
Body (json): allowedDomains array, dailyCap integer, inboundMode string, inboxId integer, password string, rampEnabled boolean, replyToInboxId integer, username string
Change a sending provider connection's reply handling, cap, ramp, allowed domains or SMTP preset login.
PATCH /api/v1/sending-provider-connections/{connectionId}. Needs the sending_providers flag and the integrations
feature (Admin). Sends Ken-Version 1.1. Only the fields you pass change; the key cannot be changed here (delete
and connect again). Same values and checks as create; passing inbound_mode or reply_to_inbox_id applies create's
Reply-To inbox rule again (receive-only, or the warning reply_to_inbox_sends:{campaign count}). allowed_domains is
staff only, except on Azure
Communication Services Email; Kenso rereads the provider's domains after it changes. 400 validation_failed detail
provider_inbound_unsupported when inbound_mode=provider on a provider that does not receive mail, staff_only,
invalid_daily_cap, invalid_domain or reply_to_inbox_required.
SMTP preset only: password (with username if the preset needs one, inbox_id if it has several inboxes) replaces
that inbox's SMTP login, stored only after it logs in; redacted from results. 400 login_rejected,
credentials_required, inbox_required, not_applicable; 403 not_your_inbox; 409 key_busy; 503 key_check_inconclusive.
404 not_found for a connection outside the workspace. Returns the connection (fields of get).
video-provider-connections-update
Write. PATCH https://api.ken.so/v1/video-provider-connections/{connectionId}
Path: connectionId
Body (json): accountLabel string, apiKey string, apiSecret string, endpointUrl string, sendsparkWorkspaceId string
Rename a campaign video provider connection or replace its credentials.
PATCH /api/v1/video-provider-connections/{connectionId}. Needs the campaigns page and the integrations feature
(workspace Admin). Sends Ken-Version 1.1. Only what you pass changes; a blank account_label clears it.
credentials (same object as create, api_key required) replaces the stored credentials: Kenso checks them with the
provider first and stores nothing when they fail, and HeyGen moves its webhook to the new key. The credentials are
never returned and are redacted from any result or error. 400 validation_failed detail invalid_credentials,
invalid_account_label or provider_not_supported; 409 key_busy; 503 provider_unavailable (retry after
Retry-After); 404 not_found for a connection outside the workspace. Early access: 404 not_found until the
workspace has the campaign_videos flag, and 403 detail feature_disabled while the provider's own flag is off.
Returns the connection (fields of video-provider-connections-get).
verify
Write. POST https://api.ken.so/v1/sending-provider-connections/{connectionId}/verify
Path: connectionId
Recheck a sending provider connection's key and domains.
POST /api/v1/sending-provider-connections/{connectionId}/verify. Needs the sending_providers flag and the
integrations feature (Admin). Sends Ken-Version 1.1. Kenso checks the stored key with one provider call. A rejected
key sets status error and lastError key_rejected. An accepted key rereads verifiedDomains and inboundDomains,
sets status connected and releases the campaigns held on the connection. On a provider with projects, a stored project the account no
longer lists sets status error and lastError project_missing (verify never picks another project; delete and
connect again to choose one), and a key that may not read projects lastError key_scope_missing. A project-based or
Sequenzy connection without a webhook secret gets Kenso's webhook again (Sequenzy reuses or replaces the one at
Kenso's URL and never adds a second; replacing needs webhooks:delete, and a key without it still verifies, with the
warning key_scope_missing:webhooks:delete).
400 validation_failed detail key_scope_missing when the key lacks a scope Kenso needs (Sequenzy; the message names
it) or may not read its domains, and 503 detail key_check_inconclusive or provider_unavailable when the provider
does not answer (nothing changes either way).
A connection the bounce guard paused (status error, lastError bounce_guard_paused: its hard bounces or complaints
crossed a line over at least 1000 sends) goes back to connected on a verify whose key checks out. Check the list
first: the guard judges it again once 1000 sends after the verify are in. A guard-paused managed connection
(kind managed, on Kenso's shared provider account) resumes only for Kenso staff (super_admin): anyone else gets 403
forbidden detail bounce_guard_staff_only and nothing changes, so tell the workspace to contact Kenso. A BYOK
connection resumes for the workspace.
An SMTP preset connection logs in with each inbox's SMTP login instead: a login_rejected:{inboxId} warning per
refused login (that inbox stops sending); no_logins when there was none to check.
Returns the connection (fields of get).
video-provider-connections-verify
Write. POST https://api.ken.so/v1/video-provider-connections/{connectionId}/verify
Path: connectionId
Check a campaign video provider connection's stored credentials again.
POST /api/v1/video-provider-connections/{connectionId}/verify. Needs the campaigns page and the integrations
feature (workspace Admin). Sends Ken-Version 1.1. A refused or unreadable key answers 200 with status error and a
plain lastError. HeyGen registers Kenso's webhook again when it has none. Sendspark and Vidyard stay unverified
until their first event. 400 detail provider_not_supported; 503 provider_unavailable (nothing changes; retry after
Retry-After); 404 not_found for a connection outside the workspace. Early access: 404 not_found until the
workspace has the campaign_videos flag, and 403 detail feature_disabled while the provider's own flag is off.
Returns the connection (fields of video-provider-connections-get).