Skip to Content
Inbox

Inbox imports

Connect many sending inboxes at once.

Inbox1 endpointKen-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.

Import SMTP inboxes

POST/v1/inbox-importsinbox-imports.create
Permission
Delivery edit
Rate limit
10 requests a minute per API key
Needs the inbox_csv_import feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

Connects up to 500 SMTP and IMAP mailboxes in the background and returns the import job with 202. Use it to load many inboxes at once, for example from a CSV file.

Send rows: from 1 to 500 inboxes, each with the fields of POST /v1/inboxes. Kenso connects each row the way POST /v1/inboxes does, with its field checks, the mailbox limit of a white-label workspace and a live SMTP and IMAP login, up to four rows at a time. A row logs in before Kenso creates its inbox, so a failed login creates nothing.

Row results:

  • A row with a missing field fails on its own, and the other rows still run.
  • A row that uses an earlier row's username on the same smtpHost or imapHost with a different password fails.
  • A row with the same email as an earlier row is skipped with duplicate_in_file.
  • A row whose email the workspace already has is skipped with already_exists, unless that inbox is a disconnected SMTP inbox. Then the row reconnects it.
  • A row fails with email_in_use when another inbox in Kenso has the address. Kenso reports it only after a successful login.
  • A row fails with host_failure_limit, without a login, when its smtpHost or imapHost refused too many logins or could not be reached several times earlier in the import.
  • A row's firstName and lastName (1 to 40 characters each, blank means none) and dailySendLimit (a whole number of 1 or more) are set on the mailbox once it connects, the way PATCH /v1/inboxes/{inboxId} sets them. A value that is not valid fails that row, with details[].field naming the column, before any login. A limit above the mailbox's provider ceiling is stored at the ceiling (50 for Google and Microsoft, 30 for custom SMTP and Azure) and the row carries the warning daily_limit_clamped. A connected row reports the firstName, lastName and dailySendLimit now on the mailbox. If the mailbox connects but those cannot be saved, the row is still connected with the warning settings_not_applied.

Poll GET /v1/jobs/{jobId}?type=inbox_import for the inboxImport counts and rows. A job with no progress for 10 minutes fails with error.code interrupted. Kenso never stores or returns the passwords.

Kenso checks the caller's access and the feature again before each row. If the feature is turned off, or the caller is no longer a member with Delivery edit, the import stops. Every row it had not started is skipped with feature_disabled or forbidden, and the job fails with that error.code.

Errors:

  • 400 validation_failed: rows is empty or has more than 500 rows.
  • 403 permission_denied: the caller does not have Delivery edit.
  • 403 forbidden: no member of the workspace is behind the credential.
  • 409 conflict: the workspace already has 2 imports queued or running.
  • 429 quota_exceeded: the import would pass the limit of 1,000 rows per workspace per rolling day. Each row that passes the field and duplicate checks counts. Nothing runs, and Retry-After says when to try again.
  • 503 service_unavailable: imports are busy. Try again in a few minutes.

Requires Delivery edit.

Request body

application/json, optional.

FieldTypeRequiredDescription
rowsarray of CreateInboxImportRowoptionalThe mailboxes to connect, from 1 to 500 rows, usually read from a CSV file.
Request
curl -X POST "https://api.ken.so/v1/inbox-imports" \
  -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 '{
  "rows": [
    {
      "email": "[email protected]",
      "firstName": "Jane",
      "lastName": "Doe",
      "username": "email",
      "password": "string",
      "smtpHost": "string",
      "smtpPort": 1,
      "imapHost": "string",
      "imapPort": 1,
      "smtpStartTls": true,
      "dailySendLimit": 1
    }
  ]
}'

Response 202

data is a Job.

Show the 14 response fields and an example

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


On this page