Skip to Content
Inbox

Attachments

Upload a file to attach to an outgoing message, download attachments and delete unsent ones.

Inbox3 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.

Upload an attachment

POST/v1/attachmentsattachments.create
Permission
Inbox edit
Rate limit
4,800 requests a minute per API key

Try it on developer.ken.so

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: messageId is not an email message id, file is 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.

FieldTypeRequiredDescription
filestring (binary)optionalThe file to upload, as a multipart file part.
messageIdstringoptionalThe msg_ id of the email message the file is for. LinkedIn message ids are refused.
purposestringoptionalinstagram for an Instagram reply's image, sent without messageId. Omit it for email.
Request
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

DELETE/v1/attachments/{attachmentId}attachments.delete
Permission
Inbox edit
Rate limit
4,800 requests a minute per API key

Try it on developer.ken.so

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

NameInTypeRequiredDescription
attachmentIdpathstringrequiredThe att_ id that POST /v1/attachments returned.
Request
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

Response 204
HTTP/1.1 204 No Content

Download an attachment

GET/v1/attachments/{attachmentId}/contentattachments.get-content
Permission
Inbox view
Rate limit
12,000 requests a minute per API key

Try it on developer.ken.so

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, or inline=true names 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

NameInTypeRequiredDescription
attachmentIdpathstringrequiredThe att_ id of the file.
inlinequerybooleanoptionalTrue to serve an inline image for display instead of as a download. Only inline images (JPEG, PNG, GIF, WebP and BMP) accept it.
Request
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.


On this page