Inbox imports
Connect many sending inboxes at once.
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. |
Import SMTP inboxes
/v1/inbox-importsinbox-imports.create- Permission
- Delivery edit
- Rate limit
- 10 requests a minute per API key
inbox_csv_import feature on your workspace. Until it is on, calls answer 404.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
usernameon the samesmtpHostorimapHostwith a different password fails. - A row with the same
emailas an earlier row is skipped withduplicate_in_file. - A row whose
emailthe workspace already has is skipped withalready_exists, unless that inbox is a disconnected SMTP inbox. Then the row reconnects it. - A row fails with
email_in_usewhen 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 itssmtpHostorimapHostrefused too many logins or could not be reached several times earlier in the import. - A row's
firstNameandlastName(1 to 40 characters each, blank means none) anddailySendLimit(a whole number of 1 or more) are set on the mailbox once it connects, the wayPATCH /v1/inboxes/{inboxId}sets them. A value that is not valid fails that row, withdetails[].fieldnaming 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 warningdaily_limit_clamped. A connected row reports thefirstName,lastNameanddailySendLimitnow on the mailbox. If the mailbox connects but those cannot be saved, the row is still connected with the warningsettings_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:rowsis 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, andRetry-Aftersays when to try again.503 service_unavailable: imports are busy. Try again in a few minutes.
Requires Delivery edit.
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
rows | array of CreateInboxImportRow | optional | The mailboxes to connect, from 1 to 500 rows, usually read from a CSV file. |
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.
More in Inbox:ThreadsReply templatesScheduled messagesAttachmentsInboxesLinkedIn accountsWhatsApp accountsWhatsApp settingsAll resources