Blocklist
Emails and domains Kenso never contacts: add, import from CSV, annotate and remove.
Headers
The endpoints on this page take these headers. Each endpoint's curl shows the ones it sends.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Ken-Version | header | string, one of: 2026-11-02, 1.1 | optional | 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 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-Id | header | integer (int64) | optional | 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. |
List blocklist entries
/v1/blocklist-entriesblocklist-entries.list- Permission
- Any workspace member except a Network member
- Rate limit
- 12,000 requests a minute per API key
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,sortorsourceholds an unknown value, orlimitorcursoris invalid.
Open to any workspace member.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
type | query | string | optional | Only entries of this type: email or domain. |
value | query | string | optional | Only the entry for this exact email or domain, ignoring case. |
q | query | string | optional | Only entries whose value or reason contains this text, ignoring case. |
source | query | string | optional | Only entries from these sources, comma-separated: any of manual, own_domain, customer and rule. |
hasReason | query | boolean | optional | Set to true to list only entries with a reason, or false for only entries without one. |
sort | query | string | optional | The order: createdAt lists oldest first, the default, and -createdAt lists newest first. |
includeTotal | query | boolean | optional | Set to true to add pagination.totalCount, the number of entries that match the filters. |
includeCounts | query | boolean | optional | Set to true to add counts, the workspace's entries by type and source, whatever the filters. |
cursor | query | string | optional | The nextCursor of the previous page. Omit it for the first page. |
limit | query | integer (int32) | optional | Entries per page, from 1 to 200. 50 by default. |
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
/v1/blocklist-entriesblocklist-entries.create- Permission
- The
workspace_settingspermission - Rate limit
- 4,800 requests a minute per API key
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:typeorvalueis missing or invalid,reasonis over 200 characters, or the value is already on the blocklist. The existing entry keeps its reason.400 validation_failedwith detail codeshared_mail_provider: the domain is a shared mail provider.
Requires the workspace_settings permission.
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
type | string | required | What to block: email for one address, domain for every address at a domain. Required. |
value | string | required | The email address or domain to block. Required. For a domain, a URL works: Kenso keeps the host without www.. |
reason | string | optional | Why the value is blocked. Optional, at most 200 characters. Blank stores no reason. |
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
/v1/blocklist-entries/{entryId}blocklist-entries.update- Permission
- The
workspace_settingspermission - Rate limit
- 4,800 requests a minute per API key
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 noreasonfield, orreasonis over 200 characters.404 not_found: no entry of this workspace has the id.409 invalid_state: the entry is aruleentry while blocklist rules are on. The rule sets its reason, so change the rule's reason instead.
Requires the workspace_settings permission.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
entryId | path | integer (int64) | required | The entry's id. |
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
reason | string | required | Why the value is blocked, at most 200 characters. Required. null or blank clears it. |
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
/v1/blocklist-entries/{entryId}blocklist-entries.delete- Permission
- The
workspace_settingspermission - Rate limit
- 4,800 requests a minute per API key
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 anown_domainentry, or aruleentry 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
entryId | path | integer (int64) | required | The entry's id, as GET /v1/blocklist-entries returns it. |
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
HTTP/1.1 204 No ContentCreate blocklist entries in bulk
/v1/blocklist-entries/bulk-createblocklist-entries.bulk-create- Permission
- The
workspace_settingspermission - Rate limit
- 480 requests a minute per API key
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:typeis missing or invalid, bothvaluesandentrieshold values, neither holds a value, there are more than 1,000 values, orreasonis over 200 characters.
Requires the workspace_settings permission.
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
type | string | required | The type of every value in the call: email or domain. Required. |
values | array of string | optional | The values to block, at most 1,000. Send this or entries, not both. |
reason | string | optional | Why the values are blocked. Optional, at most 200 characters. An entry's own reason wins over it. |
entries | array of BulkCreateBlocklistEntry | optional | The values to block, each with its own reason, at most 1,000. Send this or values, not both. |
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
/v1/blocklist-entries/bulk-deleteblocklist-entries.bulk-delete- Permission
- The
workspace_settingspermission - Rate limit
- 480 requests a minute per API key
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:idsis empty, holds more than 1,000 ids, or holds 0.
Requires the workspace_settings permission.
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
ids | array of integer (int64) | optional | The ids of the entries to remove, from 1 to 1,000. |
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
/v1/blocklist-entries/importsblocklist-entries.import- Permission
- The
workspace_settingspermission - Rate limit
- 480 requests a minute per API key
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:fileis missing, empty, not a CSV file or over 100,000 rows,reasonis 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.
| Field | Type | Required | Description |
|---|---|---|---|
file | string (binary) | optional | The CSV file, with an email column, a domain column or both, and an optional reason column. |
reason | string | optional | The reason for every row without its own. Optional, at most 200 characters. |
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.
More in Contacts and companies:ContactsContact importsContact exportsTagsBlocklist rulesContact fieldsCompaniesCompany dataContact behaviorAll resources