Attachments
Upload a file to attach to an outgoing message, download attachments and delete unsent ones.
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. |
Upload an attachment
/v1/attachmentsattachments.create- Permission
- Inbox edit
- Rate limit
- 4,800 requests a minute per API key
Uploads a file to send with an email reply or forward. The file stays pending until a reply or forward sends it.
Send the request as multipart/form-data with the file in file and the email message in messageId. Use the thread's newest message, the last one GET /v1/threads/{threadId}/messages lists: a reply or forward takes only files uploaded against that message. Allowed file types are PDF, JPEG, PNG, GIF, WebP, DOCX, XLSX, PPTX, TXT and CSV. Kenso checks that the file's content matches its extension. One message takes at most 5 pending files, 8 MiB per file and 10 MiB together.
Errors:
400 validation_failed:messageIdis not an email message id,fileis missing or empty, the file type is not allowed, or the file breaks a size or count limit.404 not_found: the message is not in this workspace.
An image for an Instagram reply is uploaded with purpose=instagram and no messageId, while the workspace has Instagram on (otherwise 404): one PNG, JPEG or WebP image of at most 5 MB. The att_ id goes in an Instagram reply's attachmentIds; an image no reply takes is never sent, and it cannot be deleted.
Requires Inbox edit.
Request body
multipart/form-data, optional.
| Field | Type | Required | Description |
|---|---|---|---|
file | string (binary) | optional | The file to upload, as a multipart file part. |
messageId | string | optional | The msg_ id of the email message the file is for. LinkedIn message ids are refused. |
purpose | string | optional | instagram for an Instagram reply's image, sent without messageId. Omit it for email. |
curl -X POST "https://api.ken.so/v1/attachments" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
-F "file=@./file" \
-F 'messageId=msg_ZW1haWw6NDAyMjg0LjJAZXhhbXBsZS5jb20' \
-F 'purpose=string'Response 201
data is a Attachment.
Show the 5 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Delete an attachment
/v1/attachments/{attachmentId}attachments.delete- Permission
- Inbox edit
- Rate limit
- 4,800 requests a minute per API key
Removes an uploaded file that no reply or forward has taken yet. Returns 204 with no body.
Errors:
400 validation_failed: a reply or forward already took the file, so it can no longer be removed.404 not_found: the id is malformed, or no pending upload in this workspace has it.
Requires Inbox edit.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
attachmentId | path | string | required | The att_ id that POST /v1/attachments returned. |
curl -X DELETE "https://api.ken.so/v1/attachments/att_ZW1haWw6NDAyMjg0LjJAZXhhbXBsZS5jb206MQ" \
-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 ContentDownload an attachment
/v1/attachments/{attachmentId}/contentattachments.get-content- Permission
- Inbox view
- Rate limit
- 12,000 requests a minute per API key
Returns the file's bytes with its content type. Get the att_ id from the attachments of a message in GET /v1/threads/{threadId}/messages.
By default the response is a download with the file's name. With inline=true Kenso serves an inline image for display in the page instead.
A WhatsApp file (an image or voice note on a WhatsApp thread) comes from WhatsApp each time; Kenso does not keep it. Its download is named whatsapp-{id} with the type's extension, and inline=true serves JPEG, PNG, GIF, WebP and audio inline.
Errors:
404 not_found: the id is malformed, the file is not in this workspace, Kenso no longer has the original email, orinline=truenames a file that is not an inline image.503 service_unavailable: Instagram or WhatsApp could not serve the file right now.
An Instagram file (an uploaded image, or an image or voice note in an Instagram chat) is served only while the workspace has Instagram on and the chat is visible. A chat's file comes from Instagram each time; Kenso does not keep it. inline=true serves images and audio inline, and every other type downloads.
Requires Inbox view.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
attachmentId | path | string | required | The att_ id of the file. |
inline | query | boolean | optional | True to serve an inline image for display instead of as a download. Only inline images (JPEG, PNG, GIF, WebP and BMP) accept it. |
curl -X GET "https://api.ken.so/v1/attachments/att_ZW1haWw6NDAyMjg0LjJAZXhhbXBsZS5jb206MQ/content" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
The body is a string (binary).
Show an example response
The fields and an example are also on this endpoint's Markdown page.
More in Inbox:ThreadsReply templatesScheduled messagesInboxesInbox importsLinkedIn accountsWhatsApp accountsWhatsApp settingsAll resources