Kiteworks mail API
The mail API from Kiteworks — 29 operation(s) for mail.
OpenAPI Specification
openapi: 3.0.2
info:
version: '28'
title: Kiteworks API Documentation activities mail API
tags:
- name: mail
paths:
/rest/mail:
get:
summary: Get messages in mail folders
description: "### Description:\n Gets a list of messages from the current user's mailbox folders: Inbox, Sent & Tracked, Drafts, Trash, and Outbox. Each result includes the email ID, sent date, and send status.\n### Precondition:\n None.\n### Response:\n Returns the list of messages across the user's mail folders.\n### Sorting:\n Sort string syntax `FIELD_NAME:ORDER`.\n\n ORDER can be `asc` or `desc`.\n### Sorting options:\n | FIELD_NAME | Description |\n |------------|--------------------------|\n | id | The mail ID |\n | date | The date the mail was sent |\n | status | The current mail status |\n"
tags:
- mail
parameters:
- in: query
name: returnEntity
required: false
description: If true, includes the entity in the response body.
schema:
type: boolean
- in: query
name: with
required: false
description: Specifies additional fields to include in the response.
schema:
type: string
- in: query
name: mode
required: false
description: Determines the detail level of the response body.
schema:
type: string
enum:
- compact
- full_no_links
- full_with_links
- full
- in: query
name: senderId
required: false
description: Unique identifier of the user who sent the email.
schema:
type: string
- in: query
name: senderId:in
required: false
explode: true
style: form
description: Unique identifier of the user who sent the email. Search for results that match any of the specified values of this parameter. (Recommended request size <= 100)
schema:
type: array
items:
type: string
- in: query
name: isRecipient
required: false
description: Filter results to include only emails where the current user is a recipient.
schema:
type: boolean
- in: query
name: read
required: false
description: Filter results based on whether the email has been read by the current user.
schema:
type: boolean
- in: query
name: date
required: false
description: Filter results by the email creation date.
schema:
type: string
format: date
- in: query
name: date:gt
required: false
description: Filter emails created after the specified date.
schema:
type: string
format: date
- in: query
name: date:gte
required: false
description: Filter emails created on or after the specified date.
schema:
type: string
format: date
- in: query
name: date:lt
required: false
description: Filter emails created before the specified date.
schema:
type: string
format: date
- in: query
name: date:lte
required: false
description: Filter emails created on or before the specified date.
schema:
type: string
format: date
- in: query
name: modified_date
required: false
description: Filter emails by the last modified date of the email.
schema:
type: string
format: date
- in: query
name: modified_date:gt
required: false
description: Filter emails modified after the specified date.
schema:
type: string
format: date
- in: query
name: modified_date:gte
required: false
description: Filter emails modified on or after the specified date.
schema:
type: string
format: date
- in: query
name: modified_date:lt
required: false
description: Filter emails modified before the specified date.
schema:
type: string
format: date
- in: query
name: modified_date:lte
required: false
description: Filter emails modified on or before the specified date.
schema:
type: string
format: date
- in: query
name: deleted
required: false
description: Indicates whether the email has been deleted.
schema:
type: boolean
- in: query
name: emailPackageId
required: false
description: Filter results by the unique identifier of the email package.
schema:
type: string
- in: query
name: emailPackageId:in
required: false
explode: true
style: form
description: Filter results by email package identifiers. Matches any of the specified values.
schema:
type: array
items:
type: string
- in: query
name: templateId
required: false
description: Filter results by the unique identifier of the email template.
schema:
type: integer
- in: query
name: templateId:in
required: false
explode: true
style: form
description: Filter results by email template identifiers. Matches any of the specified values.
schema:
type: array
items:
type: integer
- in: query
name: status
required: false
explode: true
style: form
description: Filter results by email status. Accepts a comma-separated list of values.<br>`sent` – Successfully delivered to recipients.<br>`draft` – Saved but not yet sent.<br>`queued` – Waiting to be sent.<br>`error` – Failed to send.<br>`self_send` – Sent only to the sender (self-copy only).<br>`pending_review` – Awaiting DLP or admin approval.<br>`denied` – Rejected by a DLP or admin policy.
schema:
type: array
items:
type: string
enum:
- sent
- draft
- queued
- error
- self_send
- pending_review
- denied
- in: query
name: isPreview
required: false
description: Filter results to include only preview emails if set to true.
schema:
type: boolean
- in: query
name: isUserSent
required: false
description: Filter results to include only emails sent by the user if set to true.
schema:
type: boolean
- in: query
name: bucket
required: false
description: Filter results to emails in the specified mailbox bucket.<br>`inbox` – Received emails.<br>`draft` – Unsent draft emails.<br>`outgoing` – Emails queued or in progress.<br>`sent` – Successfully sent emails.<br>`trash` – Deleted emails.
schema:
type: string
enum:
- inbox
- draft
- outgoing
- sent
- trash
- in: query
name: returnCustomWebForm
required: false
description: Includes emails with custom web forms in the results.
schema:
type: boolean
- in: query
name: customWebFormOnly
required: false
description: Filter results to only include emails with custom web forms.
schema:
type: boolean
- in: query
name: trackingOnly
required: false
description: Filter results to only include emails with tracking access.
schema:
type: boolean
- in: query
name: approvalRequestOnly
required: false
description: Filter results to only include emails with approval requests.
schema:
type: boolean
- in: query
name: webFormId
required: false
description: Filter results by unique identifier of the email web form.
schema:
type: string
format: uuid
- in: query
name: orderBy
required: false
description: 'Sort order for the results. Default is `id:asc`.<br>Allowed values: `id:asc`, `id:desc`, `date:asc`, `date:desc`, `status:asc`, `status:desc`.'
schema:
type: string
enum:
- id:asc
- id:desc
- date:asc
- date:desc
- status:asc
- status:desc
- in: query
name: sharedMailboxId
required: false
description: Unique identifier of the shared mailbox. Filters results to emails belonging to the shared mailbox.
schema:
type: string
- in: query
name: limit
required: false
description: Range limit.
schema:
type: integer
minimum: 1
- in: query
name: offset
required: false
description: Range offset.
schema:
type: integer
minimum: 0
responses:
'200':
description: Messages returned successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Mails'
'490':
description: Request blocked by WAF
delete:
summary: Delete draft messages
description: "### Description:\n Using email IDs, deletes up to 100 draft messages from the current user's Drafts folder.\n### Precondition:\n None.\n### Response:\n Deletes the specified draft messages from the Drafts folder.\n"
tags:
- mail
parameters:
- in: query
name: emailId:in
required: true
explode: true
style: form
description: Comma-separated list of email IDs to be processed.
schema:
type: array
items:
type: string
- in: query
name: partialSuccess
required: false
description: If set to `true`, the operation will continue for the valid items even if some items result in failure.
schema:
type: boolean
responses:
'204':
description: Email messages deleted successfully.
'207':
description: Some email messages were deleted successfully while others failed.
'401':
description: 'Unauthorized<br /><br /><i>Possible error codes: </i>ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED'
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
ERR_AUTH_INVALID_CSRF:
summary: Invalid CSRF Authentication
description: Invalid CSRF Authentication
value:
errors:
- code: ERR_AUTH_INVALID_CSRF
message: Invalid CSRF Authentication
ERR_AUTH_UNAUTHORIZED:
summary: Unauthorized
description: Unauthorized
value:
errors:
- code: ERR_AUTH_UNAUTHORIZED
message: Unauthorized
'403':
description: 'Forbidden<br /><br /><i>Possible error codes: </i>ERR_ACCESS_NOT_SENDER, ERR_ACCESS_USER, ERR_ENTITY_EMAIL_IS_SENT, ERR_PROFILE_MAIL_DISABLED, ERR_ENTITY_DELETED'
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
ERR_ACCESS_NOT_SENDER:
summary: Authenticated user is not the sender of the specified email
description: Authenticated user is not the sender of the specified email
value:
errors:
- code: ERR_ACCESS_NOT_SENDER
message: Authenticated user is not the sender of the specified email
ERR_ACCESS_USER:
summary: Insufficient access permissions
description: Insufficient access permissions
value:
errors:
- code: ERR_ACCESS_USER
message: Insufficient access permissions
ERR_ENTITY_EMAIL_IS_SENT:
summary: Email can no longer be deleted
description: Email can no longer be deleted
value:
errors:
- code: ERR_ENTITY_EMAIL_IS_SENT
message: Email can no longer be deleted
ERR_PROFILE_MAIL_DISABLED:
summary: User's profile has no mail access
description: User's profile has no mail access
value:
errors:
- code: ERR_PROFILE_MAIL_DISABLED
message: User's profile has no mail access
ERR_ENTITY_DELETED:
summary: Entity is deleted
description: Entity is deleted
value:
errors:
- code: ERR_ENTITY_DELETED
message: Entity is deleted
'490':
description: Request blocked by WAF
/rest/mail/actions/counters:
get:
summary: Get message counts for mail folders
description: "### Description:\n Gets the number of messages in each of the current user's mailbox folders: Inbox, Sent & Tracked, Drafts, Trash, and Outbox.\n### Precondition:\n None.\n### Response:\n Returns the message count for each mail folder.\n"
tags:
- mail
parameters:
- in: query
name: returnCustomWebForm
required: false
description: Indicates whether to include emails with custom web forms in the result.
schema:
type: boolean
responses:
'200':
description: Message counts returned successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/MailCounters'
'401':
description: 'Unauthorized<br /><br /><i>Possible error codes: </i>ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED'
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
ERR_AUTH_INVALID_CSRF:
summary: Invalid CSRF Authentication
description: Invalid CSRF Authentication
value:
errors:
- code: ERR_AUTH_INVALID_CSRF
message: Invalid CSRF Authentication
ERR_AUTH_UNAUTHORIZED:
summary: Unauthorized
description: Unauthorized
value:
errors:
- code: ERR_AUTH_UNAUTHORIZED
message: Unauthorized
'490':
description: Request blocked by WAF
/rest/mail/actions/deletePermanent:
patch:
summary: Permanently delete messages
description: "### Description:\n Using email IDs, permanently deletes messages from the current user's Inbox and Sent folders. Depending on the system retention policy, messages may be recoverable until they are permanently purged by the system.\n### Preconditions:\n Must be the sender or a recipient of the messages.\n### Response:\n Returns a full or partial success response indicating which messages were permanently deleted.\n"
tags:
- mail
parameters:
- in: query
name: emailId:in
required: true
explode: true
style: form
description: Comma-separated list of email IDs to be processed.
schema:
type: array
items:
type: string
- in: query
name: partialSuccess
required: false
description: If set to `true`, the operation will continue for the valid items even if some items result in failure.
schema:
type: boolean
responses:
'200':
description: Messages permanently deleted successfully.
'207':
description: Partially successful — some messages could not be permanently deleted.
content:
application/json:
schema:
$ref: '#/components/schemas/BulkOperationInteger'
'401':
description: 'Unauthorized<br /><br /><i>Possible error codes: </i>ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED'
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
ERR_AUTH_INVALID_CSRF:
summary: Invalid CSRF Authentication
description: Invalid CSRF Authentication
value:
errors:
- code: ERR_AUTH_INVALID_CSRF
message: Invalid CSRF Authentication
ERR_AUTH_UNAUTHORIZED:
summary: Unauthorized
description: Unauthorized
value:
errors:
- code: ERR_AUTH_UNAUTHORIZED
message: Unauthorized
'403':
description: 'Forbidden<br /><br /><i>Possible error codes: </i>ERR_ACCESS_USER, ERR_ENTITY_NOT_DELETED, ERR_ENTITY_EMAIL_IS_NOT_COMPLETED'
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
ERR_ACCESS_USER:
summary: Insufficient access permissions
description: Insufficient access permissions
value:
errors:
- code: ERR_ACCESS_USER
message: Insufficient access permissions
ERR_ENTITY_NOT_DELETED:
summary: Entity is not deleted
description: Entity is not deleted
value:
errors:
- code: ERR_ENTITY_NOT_DELETED
message: Entity is not deleted
ERR_ENTITY_EMAIL_IS_NOT_COMPLETED:
summary: Email is not completed
description: Email is not completed
value:
errors:
- code: ERR_ENTITY_EMAIL_IS_NOT_COMPLETED
message: Email is not completed
'410':
description: 'Gone<br /><br /><i>Possible error codes: </i>ERR_ENTITY_DELETED_PERMANENTLY'
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
ERR_ENTITY_DELETED_PERMANENTLY:
summary: Entity is deleted permanently
description: Entity is deleted permanently
value:
errors:
- code: ERR_ENTITY_DELETED_PERMANENTLY
message: Entity is deleted permanently
'490':
description: Request blocked by WAF
/rest/mail/actions/distributionList:
get:
tags:
- mail
summary: Expand a distribution list
description: Resolves a distribution list email address and returns its members.
responses:
'200':
description: Returns the distribution list with its resolved member email addresses.
content:
application/json:
schema:
$ref: '#/components/schemas/DistributionList'
examples:
DistributionListExpanded:
summary: A resolved distribution list
value:
isDistributionList: true
members:
- engineering@example.com
- design@example.com
'403':
description: 'Forbidden<br /><br /><i>Possible error codes: </i>ERR_ACCESS_USER'
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
ERR_ACCESS_USER:
summary: Insufficient access permissions
description: Insufficient access permissions
value:
errors:
code: ERR_ACCESS_USER
message: Insufficient access permissions
'490':
description: Request blocked by WAF
deprecated: false
parameters:
- in: query
name: email
description: The email address to check or expand.
required: true
schema:
type: string
- in: query
name: expand
description: Indicates whether to include the email addresses of distribution list members.
schema:
type: boolean
- in: query
name: emailId
description: If provided, the distribution list will include only members who have received this specific email.
schema:
type: string
/rest/mail/actions/read:
patch:
summary: Mark messages as read
description: "### Description:\n Using email IDs, marks the specified messages as read in the current user's Inbox.\n### Preconditions:\n Must be the sender or a recipient of the messages.\n### Response:\n Returns a full or partial success response indicating which messages were marked as read.\n"
tags:
- mail
parameters:
- in: query
name: emailId:in
required: true
explode: true
style: form
description: Comma-separated list of email IDs to be processed.
schema:
type: array
items:
type: string
- in: query
name: partialSuccess
required: false
description: If set to `true`, the operation will continue for the valid items even if some items result in failure.
schema:
type: boolean
responses:
'200':
description: Email messages marked as read successfully.
'207':
description: Partially successful — some messages could not be marked as read.
content:
application/json:
schema:
$ref: '#/components/schemas/BulkOperationInteger'
'401':
description: 'Unauthorized<br /><br /><i>Possible error codes: </i>ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED'
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
ERR_AUTH_INVALID_CSRF:
summary: Invalid CSRF Authentication
description: Invalid CSRF Authentication
value:
errors:
- code: ERR_AUTH_INVALID_CSRF
message: Invalid CSRF Authentication
ERR_AUTH_UNAUTHORIZED:
summary: Unauthorized
description: Unauthorized
value:
errors:
- code: ERR_AUTH_UNAUTHORIZED
message: Unauthorized
'403':
description: 'Forbidden<br /><br /><i>Possible error codes: </i>ERR_ACCESS_USER, ERR_ENTITY_DELETED'
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
ERR_ACCESS_USER:
summary: Insufficient access permissions
description: Insufficient access permissions
value:
errors:
- code: ERR_ACCESS_USER
message: Insufficient access permissions
ERR_ENTITY_DELETED:
summary: Entity is deleted
description: Entity is deleted
value:
errors:
- code: ERR_ENTITY_DELETED
message: Entity is deleted
'490':
description: Request blocked by WAF
/rest/mail/actions/recover:
patch:
summary: Recover deleted messages
description: "### Description:\n Using email IDs, recovers deleted messages from the current user's Trash folder and returns them to the Inbox.\n### Preconditions:\n Must be the sender or a recipient of the messages.\n### Response:\n Returns a full or partial success response indicating which messages were recovered to the Inbox.\n"
tags:
- mail
parameters:
- in: query
name: emailId:in
required: true
explode: true
style: form
description: Comma-separated list of email IDs to be processed.
schema:
type: array
items:
type: string
- in: query
name: partialSuccess
required: false
description: If set to `true`, the operation will continue for the valid items even if some items result in failure.
schema:
type: boolean
responses:
'200':
description: Messages recovered successfully.
'207':
description: Partially successful — some messages could not be recovered.
content:
application/json:
schema:
$ref: '#/components/schemas/BulkOperationInteger'
'401':
description: 'Unauthorized<br /><br /><i>Possible error codes: </i>ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED'
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
ERR_AUTH_INVALID_CSRF:
summary: Invalid CSRF Authentication
description: Invalid CSRF Authentication
value:
errors:
- code: ERR_AUTH_INVALID_CSRF
message: Invalid CSRF Authentication
ERR_AUTH_UNAUTHORIZED:
summary: Unauthorized
description: Unauthorized
value:
errors:
- code: ERR_AUTH_UNAUTHORIZED
message: Unauthorized
'403':
description: 'Forbidden<br /><br /><i>Possible error codes: </i>ERR_ACCESS_USER, ERR_ENTITY_NOT_DELETED, ERR_ENTITY_EMAIL_IS_NOT_COMPLETED'
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
ERR_ACCESS_USER:
summary: Insufficient access permissions
description: Insufficient access permissions
value:
errors:
- code: ERR_ACCESS_USER
message: Insufficient access permissions
ERR_ENTITY_NOT_DELETED:
summary: Entity is not deleted
description: Entity is not deleted
value:
errors:
- code: ERR_ENTITY_NOT_DELETED
message: Entity is not deleted
ERR_ENTITY_EMAIL_IS_NOT_COMPLETED:
summary: Email is not completed
description: Email is not completed
value:
errors:
- code: ERR_ENTITY_EMAIL_IS_NOT_COMPLETED
message: Email is not completed
'410':
description: 'Gone<br /><br /><i>Possible error codes: </i>ERR_ENTITY_DELETED_PERMANENTLY'
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
ERR_ENTITY_DELETED_PERMANENTLY:
summary: Entity is deleted permanently
description: Entity is deleted permanently
value:
errors:
- code: ERR_ENTITY_DELETED_PERMANENTLY
message: Entity is deleted permanently
'490':
description: Request blocked by WAF
/rest/mail/actions/sendFile:
post:
summary: Send files
description: "### Description:\n Creates an email message and sends the specified file attachments through Kiteworks.\n### Precondition:\n Must be assigned a user profile with permission to send mail.\n### Response:\n Returns the created email and sends the file attachments to the specified recipients.\n"
tags:
- mail
parameters:
- in: query
name: returnEntity
required: false
description: If true, includes the entity in the response body.
schema:
type: boolean
- in: query
name: with
required: false
description: Specifies additional fields to include in the response.
schema:
type: string
- in: query
name: mode
required: false
description: Determines the detail level of the response body.
schema:
type: string
enum:
- compact
- full_no_links
- full_with_links
- full
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BaseSendMailPostRequest'
responses:
'201':
description: Email created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Mail'
'401':
description: 'Unauthorized<br /><br /><i>Possible error codes: </i>ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED'
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
ERR_AUTH_INVALID_CSRF:
summary: Invalid CSRF Authentication
description: Invalid CSRF Authentication
value:
errors:
- code: ERR_AUTH_INVALID_CSRF
message: Invalid CSRF Authentication
ERR_AUTH_UNAUTHORIZED:
summary: Unauthorized
description: Unauthorized
value:
errors:
- code: ERR_AUTH_UNAUTHORIZED
message: Unauthorized
'403':
description: 'Forbidden<br /><br /><i>Possible error codes: </i>ERR_ACCESS_USER, ERR_ENTITY_DELETED, ERR_ENTITY_IS_DELETED_ATTACHMENT, ERR_ENTITY_IS_SECURE_FOLDER, ERR_INPUT_EMAIL_WITH_NO_RECIPIENTS_NOT_ALLOWED, ERR_INPUT_SECURE_BODY_WITH_NO_AUTH_NOT_ALLOWED, ERR_PROFILE_INCLUDE_FINGERPRINT_DISABLED, ERR_PROFILE_INCLUDE_FINGERPRINT_ENABLED, ERR_PROFILE_RETURN_RECEIPT_DISABLED, ERR_PROFILE_RETURN_RECEIPT_ENABLED, ERR_PROFILE_SECURE_EMAIL_DISABLED, ERR_PROFILE_SELF_COPY_DISABLED, ERR_PROFILE_SELF_COPY_ENABLED, ERR_PROFILE_SEND_FILE_EXTERNAL_DISABLED, ERR_USER_HAS_NO_USER_TYPE, ERR_USER_TYPE_NO_ACCESS'
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
ERR_ACCESS_USER:
summary: Insufficient access permissions
description: Insufficient access permissions
value:
errors:
- code: ERR_ACCESS_USER
message: Insufficient access permissions
ERR_ENTITY_DELETED:
summary: Entity is deleted
description: Entity is deleted
value:
errors:
- code: ERR_ENTITY_DELETED
message: Entity is deleted
ERR_ENTITY_IS_DELETED_ATTACHMENT:
summary: Requested Attachment(s) is deleted
description: Requested Attachment(s) is deleted
value:
errors:
- code: ERR_ENTITY_IS_DELETED_ATTACHMENT
message: Requested Attachment(s) is deleted
ERR_ENTITY_IS_SECURE_FOLDER:
summary: Operation not permitted on restricted Folder.
description: Operation not permitted
# --- truncated at 32 KB (168 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/kiteworks/refs/heads/main/openapi/kiteworks-mail-api-openapi.yml