Inbox

/api/v1 operations for inbox. See HTTP API for authentication, the error envelope, and rate limits.

Operations

GET /api/v1/inbox

Get the workspace inbox

Returns the address and sender name of the workspace's email inbox on agents.khotan.com, creating the inbox if the workspace has none yet.

Auth: API key required.

Operation ID: getWorkspaceInbox

Responses:

• 200 — The workspace inbox.
• 401 — Authentication is missing or invalid.
• 403 — The caller is not permitted to perform this action.
• 429 — Too many requests; retry after the indicated delay.

GET /api/v1/inbox/threads

List email threads

Lists the workspace inbox's email threads, newest first. Filter by text in a sender or the subject. Set excludeInternal=true to leave out email that staff sent from the internal channel.

Auth: API key required.

Operation ID: listInboxThreads

Query parameters:

• limit (integer, optional)
• pageToken (string, optional)
• sender (string, optional)
• subject (string, optional)
• excludeInternal ("true" | "false", optional)

Responses:

• 200 — Email threads.
• 401 — Authentication is missing or invalid.
• 403 — The caller is not permitted to perform this action.
• 429 — Too many requests; retry after the indicated delay.

GET /api/v1/inbox/threads/{threadId}

Read an email thread

Returns every message in one email thread of the workspace inbox, with each message's sender, recipients, body text, and attachments.

Auth: API key required.

Operation ID: getInboxThread

Path parameters:

• threadId (string, required)

Query parameters:

• excludeInternal ("true" | "false", optional)

Responses:

• 200 — The email thread.
• 401 — Authentication is missing or invalid.
• 403 — The caller is not permitted to perform this action.
• 404 — The resource was not found.
• 429 — Too many requests; retry after the indicated delay.

GET /api/v1/inbox/messages/{messageId}/attachments/{attachmentId}

Get an email attachment

Returns an attachment's name, type, and size, with short-lived links to its bytes and, when available, its extracted text.

Auth: API key required.

Operation ID: getInboxAttachment

Path parameters:

• messageId (string, required)
• attachmentId (string, required)

Query parameters:

• excludeInternal ("true" | "false", optional)

Responses:

• 200 — The attachment links.
• 401 — Authentication is missing or invalid.
• 403 — The caller is not permitted to perform this action.
• 404 — The resource was not found.
• 429 — Too many requests; retry after the indicated delay.

POST /api/v1/inbox/drafts

Create an email draft

Creates an unsent draft in the workspace inbox: a new email with recipients and a subject, or a reply to a message in the inbox. Nothing is sent until the draft is sent.

Auth: API key required.

Operation ID: createInboxDraft

Request body (application/json, required):

• to (string[], optional)
• cc (string[], optional)
• subject (string, optional)
• text (string, required)
• replyToMessageId (string, optional)
• replyAll (boolean, optional)
• internal (boolean, optional)
• slackThread (object, optional)

Responses:

• 201 — The draft.
• 400 — The request was malformed or failed validation.
• 401 — Authentication is missing or invalid.
• 403 — The caller is not permitted to perform this action.
• 404 — The resource was not found.
• 429 — Too many requests; retry after the indicated delay.

DELETE /api/v1/inbox/drafts/{draftId}

Discard an email draft

Deletes an unsent draft from the workspace inbox, so it can never be sent.

Auth: API key required.

Operation ID: discardInboxDraft

Path parameters:

• draftId (string, required)

Responses:

• 204 — The draft was discarded.
• 401 — Authentication is missing or invalid.
• 403 — The caller is not permitted to perform this action.
• 404 — The resource was not found.
• 429 — Too many requests; retry after the indicated delay.

POST /api/v1/inbox/drafts/{draftId}/send

Send an email draft

Sends a draft from the workspace inbox. A draft sends once; after it sends, it no longer exists.

Auth: API key required.

Operation ID: sendInboxDraft

Path parameters:

• draftId (string, required)

Responses:

• 200 — The sent email.
• 401 — Authentication is missing or invalid.
• 403 — The caller is not permitted to perform this action.
• 404 — The resource was not found.
• 429 — Too many requests; retry after the indicated delay.