Skip to Content
Contacts and companies

Blocklist

Emails and domains Kenso never contacts: add, import from CSV, annotate and remove.

Contacts and companies7 endpointsKen-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.

List blocklist entries

GET/v1/blocklist-entriesblocklist-entries.list
Permission
Any workspace member except a Network member
Rate limit
12,000 requests a minute per API key

Try it on developer.ken.so

Lists the workspace's blocklist entries, oldest first. Use the filters to check whether an email or domain is blocked, or to review entries by source.

sort=-createdAt lists newest first. Keep the same sort while you page. includeTotal=true adds pagination.totalCount, the number of entries that match the filters. includeCounts=true adds counts, the workspace's entries per type and source, whatever filters you send.

Errors:

  • 400 validation_failed: type, sort or source holds an unknown value, or limit or cursor is invalid.

Open to any workspace member.

Parameters

NameInTypeRequiredDescription
typequerystringoptionalOnly entries of this type: email or domain.
valuequerystringoptionalOnly the entry for this exact email or domain, ignoring case.
qquerystringoptionalOnly entries whose value or reason contains this text, ignoring case.
sourcequerystringoptionalOnly entries from these sources, comma-separated: any of manual, own_domain, customer and rule.
hasReasonquerybooleanoptionalSet to true to list only entries with a reason, or false for only entries without one.
sortquerystringoptionalThe order: createdAt lists oldest first, the default, and -createdAt lists newest first.
includeTotalquerybooleanoptionalSet to true to add pagination.totalCount, the number of entries that match the filters.
includeCountsquerybooleanoptionalSet to true to add counts, the workspace's entries by type and source, whatever the filters.
cursorquerystringoptionalThe nextCursor of the previous page. Omit it for the first page.
limitqueryinteger (int32)optionalEntries per page, from 1 to 200. 50 by default.
Request
curl -X GET "https://api.ken.so/v1/blocklist-entries?limit=50" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"

Response 200

data is a list of BlocklistEntry. Each item has these fields. The response also carries pagination, counts.

Show the 7 response fields and an example

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

Create a blocklist entry

POST/v1/blocklist-entriesblocklist-entries.create
Permission
The workspace_settings permission
Rate limit
4,800 requests a minute per API key

Try it on developer.ken.so

Adds one email or domain to the blocklist. From then on, Kenso does not contact that email, or anyone at that domain.

type (email or domain) and value are required. For a domain, a URL works: Kenso keeps the host without www.. reason is optional, at most 200 characters.

A domain that a customer account or a blocklist rule already lists, or an email that only a blocklist rule lists, becomes a manual entry under the same id with your reason, and the answer has claimed: true. If the workspace's connected CRM syncs opt-outs, Kenso also marks a newly blocked email as opted out on the matching CRM contacts. Shared mail provider domains such as gmail.com, hotmail.co.uk and web.de cannot be blocked whole: block those addresses one by one.

Errors:

  • 400 validation_failed: type or value is missing or invalid, reason is over 200 characters, or the value is already on the blocklist. The existing entry keeps its reason.
  • 400 validation_failed with detail code shared_mail_provider: the domain is a shared mail provider.

Requires the workspace_settings permission.

Request body

application/json, optional.

FieldTypeRequiredDescription
typestringrequiredWhat to block: email for one address, domain for every address at a domain. Required.
valuestringrequiredThe email address or domain to block. Required. For a domain, a URL works: Kenso keeps the host without www..
reasonstringoptionalWhy the value is blocked. Optional, at most 200 characters. Blank stores no reason.
Request
curl -X POST "https://api.ken.so/v1/blocklist-entries" \
  -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 '{
  "type": "domain",
  "value": "competitor.example.com",
  "reason": "Current customer"
}'

Response 201

data is a BlocklistEntry.

Show the 7 response fields and an example

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

Update a blocklist entry's reason

PATCH/v1/blocklist-entries/{entryId}blocklist-entries.update
Permission
The workspace_settings permission
Rate limit
4,800 requests a minute per API key

Try it on developer.ken.so

Sets or clears the reason on one blocklist entry. The blocked value does not change.

Send { "reason": "..." }. The reason field is required, at most 200 characters, and null or blank clears it.

Errors:

  • 400 validation_failed: the body has no reason field, or reason is over 200 characters.
  • 404 not_found: no entry of this workspace has the id.
  • 409 invalid_state: the entry is a rule entry while blocklist rules are on. The rule sets its reason, so change the rule's reason instead.

Requires the workspace_settings permission.

Parameters

NameInTypeRequiredDescription
entryIdpathinteger (int64)requiredThe entry's id.

Request body

application/json, optional.

FieldTypeRequiredDescription
reasonstringrequiredWhy the value is blocked, at most 200 characters. Required. null or blank clears it.
Request
curl -X PATCH "https://api.ken.so/v1/blocklist-entries/812" \
  -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 '{
  "reason": "string"
}'

Response 200

data is a BlocklistEntry.

Show the 7 response fields and an example

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

Delete a blocklist entry

DELETE/v1/blocklist-entries/{entryId}blocklist-entries.delete
Permission
The workspace_settings permission
Rate limit
4,800 requests a minute per API key

Try it on developer.ken.so

Removes one entry from the blocklist.

If the value is also one of the workspace's own domains or matches an enabled blocklist rule, Kenso adds the own_domain or rule entry back right away. A customer entry deleted here stays off.

Errors:

  • 404 not_found: no entry of this workspace has the id.
  • 409 invalid_state: the entry is an own_domain entry, or a rule entry while blocklist rules are on. To unblock an own domain, remove it in Settings > Company. Only Kenso support can change the primary domain. To unblock a rule entry, change or turn off the rule.

Requires the workspace_settings permission.

Parameters

NameInTypeRequiredDescription
entryIdpathinteger (int64)requiredThe entry's id, as GET /v1/blocklist-entries returns it.
Request
curl -X DELETE "https://api.ken.so/v1/blocklist-entries/812" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"

Response 204

Response 204
HTTP/1.1 204 No Content

Create blocklist entries in bulk

POST/v1/blocklist-entries/bulk-createblocklist-entries.bulk-create
Permission
The workspace_settings permission
Rate limit
480 requests a minute per API key

Try it on developer.ken.so

Adds up to 1,000 emails, or up to 1,000 domains, to the blocklist in one call. Every value in a call has the same type.

type (email or domain) is required. Send the values in values, or in entries to give each value its own reason, not both. The optional reason, at most 200 characters, applies to every value without its own.

Kenso checks each value on its own. succeeded lists the entries it added. failed lists the values it did not add, each with a code: already_exists for a value already on the blocklist or repeated in the call (the existing entry keeps its reason), shared_mail_provider for a domain such as gmail.com, invalid for a malformed value or a reason over 200 characters, and failed for any other error. A domain that a customer account or a blocklist rule already lists, or an email that only a rule lists, becomes a manual entry under the same id and is in succeeded with claimed: true.

To undo the call, delete only the succeeded ids without claimed: true. A claimed entry was blocked before the call, and deleting it would unblock the value.

Errors:

  • 400 validation_failed: type is missing or invalid, both values and entries hold values, neither holds a value, there are more than 1,000 values, or reason is over 200 characters.

Requires the workspace_settings permission.

Request body

application/json, optional.

FieldTypeRequiredDescription
typestringrequiredThe type of every value in the call: email or domain. Required.
valuesarray of stringoptionalThe values to block, at most 1,000. Send this or entries, not both.
reasonstringoptionalWhy the values are blocked. Optional, at most 200 characters. An entry's own reason wins over it.
entriesarray of BulkCreateBlocklistEntryoptionalThe values to block, each with its own reason, at most 1,000. Send this or values, not both.
Request
curl -X POST "https://api.ken.so/v1/blocklist-entries/bulk-create" \
  -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 '{
  "type": "email",
  "values": [
    "string"
  ],
  "reason": "string",
  "entries": [
    {
      "value": "string",
      "reason": "string"
    }
  ]
}'

Response 200

data is a BlocklistBulkResult.

Show the 2 response fields and an example

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

Delete blocklist entries in bulk

POST/v1/blocklist-entries/bulk-deleteblocklist-entries.bulk-delete
Permission
The workspace_settings permission
Rate limit
480 requests a minute per API key

Try it on developer.ken.so

Removes up to 1,000 blocklist entries by id in one call. Use it to undo a large upload, 1,000 entries per call.

Send { "ids": [...] } with from 1 to 1,000 entry ids. succeeded lists, in request order, every id that is off the blocklist after the call, including an id that was already gone. failed lists the entries Kenso kept, each with an error whose code is invalid_state: an own_domain entry, or a rule entry while blocklist rules are on.

To undo a bulk create, send only its succeeded ids without claimed: true. A claimed entry was blocked before that call, by a customer account or a rule, and a customer entry deleted here stays off. As on a single delete, Kenso adds an own_domain or rule entry back right away when the value still matches.

Errors:

  • 400 validation_failed: ids is empty, holds more than 1,000 ids, or holds 0.

Requires the workspace_settings permission.

Request body

application/json, optional.

FieldTypeRequiredDescription
idsarray of integer (int64)optionalThe ids of the entries to remove, from 1 to 1,000.
Request
curl -X POST "https://api.ken.so/v1/blocklist-entries/bulk-delete" \
  -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 '{
  "ids": [
    812
  ]
}'

Response 200

data is a BlocklistBulkDeleteResult.

Show the 2 response fields and an example

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

Import blocklist entries from a CSV file

POST/v1/blocklist-entries/importsblocklist-entries.import
Permission
The workspace_settings permission
Rate limit
480 requests a minute per API key

Try it on developer.ken.so

Adds the rows of a CSV file to the blocklist. Kenso processes the whole file before it answers.

Send multipart/form-data with the field file: a .csv file with a CSV content type such as text/csv, with an email column, a domain column or both, and an optional reason column. A file holds at most 100,000 rows. A reason cell over 200 characters is cut and never fails the file. The optional form field reason, at most 200 characters, applies to every row without its own.

Rows already on the blocklist keep their own reason. A shared mail provider in the domain column, such as gmail.com, is skipped. Imported emails are not sent to the connected CRM as opt-outs. Kenso adds the rows in file order and stops at the first row with an invalid email or domain: the rows before it stay on the blocklist.

Errors:

  • 400 validation_failed: file is missing, empty, not a CSV file or over 100,000 rows, reason is over 200 characters, or a row holds an invalid email or domain. The message names the row.

Requires the workspace_settings permission.

Request body

multipart/form-data, optional.

FieldTypeRequiredDescription
filestring (binary)optionalThe CSV file, with an email column, a domain column or both, and an optional reason column.
reasonstringoptionalThe reason for every row without its own. Optional, at most 200 characters.
Request
curl -X POST "https://api.ken.so/v1/blocklist-entries/imports" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
  -F "file=@./file" \
  -F 'reason=string'

Response 200

data is a BlocklistImport.

Show the 1 response field and an example

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


On this page