Get messages in mail folders
Description:
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.Precondition:
None.Response:
Returns the list of messages across the user's mail folders.Sorting:
Sort string syntax `FIELD_NAME:ORDER`.ORDER can be asc or desc.
Sorting options:
| FIELD_NAME | Description |
|---|---|
| id | The mail ID |
| date | The date the mail was sent |
| status | The current mail status |
If true, includes the entity in the response body.
Specifies additional fields to include in the response.
Determines the detail level of the response body.
Unique identifier of the user who sent the email.
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)
Filter results to include only emails where the current user is a recipient.
Filter results based on whether the email has been read by the current user.
Filter results by the email creation date.
Filter emails created after the specified date.
Filter emails created on or after the specified date.
Filter emails created before the specified date.
Filter emails created on or before the specified date.
Filter emails by the last modified date of the email.
Filter emails modified after the specified date.
Filter emails modified on or after the specified date.
Filter emails modified before the specified date.
Filter emails modified on or before the specified date.
Indicates whether the email has been deleted.
Filter results by the unique identifier of the email package.
Filter results by email package identifiers. Matches any of the specified values.
Filter results by the unique identifier of the email template.
Filter results by email template identifiers. Matches any of the specified values.
Filter results by email status. Accepts a comma-separated list of values.sent – Successfully delivered to recipients.draft – Saved but not yet sent.queued – Waiting to be sent.error – Failed to send.self_send – Sent only to the sender (self-copy only).pending_review – Awaiting DLP or admin approval.denied – Rejected by a DLP or admin policy.
Filter results to include only preview emails if set to true.
Filter results to include only emails sent by the user if set to true.
Filter results to emails in the specified mailbox bucket.inbox – Received emails.draft – Unsent draft emails.outgoing – Emails queued or in progress.sent – Successfully sent emails.trash – Deleted emails.
Includes emails with custom web forms in the results.
Filter results to only include emails with custom web forms.
Filter results to only include emails with tracking access.
Filter results to only include emails with approval requests.
Filter results by unique identifier of the email web form.
Sort order for the results. Default is id:asc.
Allowed values: id:asc, id:desc, date:asc, date:desc, status:asc, status:desc.
Unique identifier of the shared mailbox. Filters results to emails belonging to the shared mailbox.
Range limit.
Range offset.
Messages returned successfully.
Unique identifier of the email.
Unique identifier of the sender.
Unique identifier of the email template used.
Current status of the email (e.g., sent, draft, error, etc.).
Type of the email (e.g., original, reply, forward, etc.).
Date the email was last modified or sent.
Indicates if the email has been deleted.
Date when the email was withdrawn, if applicable.
Unique identifier of the associated email package.
Indicates whether the email is a view-only version, typically used for previewing attachments without enabling downloading.
Indicates whether the email was sent by the current user or another user.
Text watermark applied to the email attachments (applicable only for view-only version).
Unique identifier of the user associated with the recipient.
Recipient type.0 – To.1 – CC.2 – BCC.
Email address of the recipient.
Indicates if the recipient is a distribution list rather than an individual user.
Unique identifier (UUID) for the user.
Email address associated with the user.
Full name of the user.
URL or identifier for the user's profile icon.
Indicates if the email body is secured.
Date the email was last modified.
Unique identifier of the parent email, if applicable.
Unique identifier of the user who requested the return receipt.
Unique identifier (UUID) for the user.
Email address associated with the user.
Full name of the user.
URL or identifier for the user's profile icon.
Error message associated with the email, if any.
Subject line of the email.
Number of attachments in the email.
Expiration date of the email package, if applicable.
Antivirus (AV) scan status of the email.
Data Loss Prevention (DLP) scan status of the email.
Indicates if tracking access is enabled for the email.
Unique identifier of the user associated with the recipient.
Recipient type.0 – To.1 – CC.2 – BCC.
Email address of the recipient.
Indicates if the recipient is a distribution list rather than an individual user.
Unique identifier (UUID) for the user.
Email address associated with the user.
Full name of the user.
URL or identifier for the user's profile icon.
Indicates whether the recipient's tracking access has been revoked.
Indicates the restriction type applied to the email
Indicates if the email has been read.
The bucket where the email is stored. (e.g. inbox, sent, trash)
The body of the email.
Unique identifier of the email package.
Indicates whether the package includes a copy for the sender.
Indicates whether a fingerprint (hash) of the package should be included for verification.
Expiration time of the package in seconds from creation.
Count of the files attached to the package.
Indicates whether the package has been marked as deleted.
Access control list (ACL) associated with the package, specifying who can access it.
Unique identifier for the email package containing the attachment.
Unique identifier for the attachment.
Indicates whether the attachment has been withdrawn.
Details of the DRM-protected file associated with the attachment.
Access type for the attachment (e.g., read-only, editable).
List of tags associated with the attachment.
List of permissions associated with the attachment.
Unique identifier for the file associated with the attachment.
Name of the attachment file.
Size of the attachment file in bytes.
The MIME type of the attachment file.
Date when the attachment file was created.
Indicates if the attachment has been deleted.
A unique hash identifying the file version.
The algorithm used for generating the file version fingerprint. (e.g., sha3-256, md5).
List of alternative fingerprints for the attachment file.
Status of the attachment in the admin quarantine system.
Antivirus (AV) scan status of the attachment.
Data Loss Prevention (DLP) status of the attachment.
Link for accessing the email.
Raw email body content without HTML markup.
Headline or main title of the email.
Notice part of the email.
Full HTML body of the email.
The email address from which the email was sent.
Body content generated from the email template.
Unique identifier of the web form associated with the email.
Fields included in the associated web form with the mail.
Unique identifier (UUID) for the user.
Email address associated with the user.
Full name of the user.
URL or identifier for the user's profile icon.
Unique identifier of the shared mailbox, if applicable.
HTML version of the email body.
Unique identifier (UUID) for the user.
Email address associated with the user.
Full name of the user.
URL or identifier for the user's profile icon.
CSS styles applied for dark mode.
Indicates whether the email already exists in the system.
Total number of items available.
Maximum number of items returned per page.
Number of items skipped before the current page.
Request blocked by WAF
curl -X GET \
"https://{instance}.kiteworks.com/rest/mail" \
-H "Authorization: Bearer YOUR_TOKEN"import requests
url = "https://{instance}.kiteworks.com/rest/mail"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())Delete draft messages
Description:
Using email IDs, deletes up to 100 draft messages from the current user's Drafts folder.Precondition:
None.Response:
Deletes the specified draft messages from the Drafts folder.Comma-separated list of email IDs to be processed.
If set to true, the operation will continue for the valid items even if some items result in failure.
Email messages deleted successfully.
Some email messages were deleted successfully while others failed.
Unauthorized
Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED
Error code
Error message
Forbidden
Possible error codes: ERR_ACCESS_NOT_SENDER, ERR_ACCESS_USER, ERR_ENTITY_EMAIL_IS_SENT, ERR_PROFILE_MAIL_DISABLED, ERR_ENTITY_DELETED
Error code
Error message
Request blocked by WAF
curl -X DELETE \
"https://{instance}.kiteworks.com/rest/mail?emailId:in=VALUE" \
-H "Authorization: Bearer YOUR_TOKEN"import requests
url = "https://{instance}.kiteworks.com/rest/mail"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
params = {
"emailId:in": "VALUE",
}
response = requests.delete(url, params=params, headers=headers)
print(response.json())Get message counts for mail folders
Description:
Gets the number of messages in each of the current user's mailbox folders: Inbox, Sent & Tracked, Drafts, Trash, and Outbox.Precondition:
None.Response:
Returns the message count for each mail folder.Indicates whether to include emails with custom web forms in the result.
Message counts returned successfully.
Number of draft emails.
Number of emails in the inbox.
Number of unread emails in the inbox.
Number of outgoing emails.
Number of outgoing emails that encountered an error.
Number of outgoing emails queued for sending.
Number of outgoing emails currently being transferred.
Number of emails in the trash.
Unauthorized
Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED
Error code
Error message
Request blocked by WAF
curl -X GET \
"https://{instance}.kiteworks.com/rest/mail/actions/counters" \
-H "Authorization: Bearer YOUR_TOKEN"import requests
url = "https://{instance}.kiteworks.com/rest/mail/actions/counters"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())Permanently delete messages
Description:
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.Preconditions:
Must be the sender or a recipient of the messages.Response:
Returns a full or partial success response indicating which messages were permanently deleted.Comma-separated list of email IDs to be processed.
If set to true, the operation will continue for the valid items even if some items result in failure.
Messages permanently deleted successfully.
Partially successful — some messages could not be permanently deleted.
Error code
Error message
Associated field, if applicable.
List of failed IDs.
List of succeeded IDs.
Unauthorized
Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED
Error code
Error message
Forbidden
Possible error codes: ERR_ACCESS_USER, ERR_ENTITY_NOT_DELETED, ERR_ENTITY_EMAIL_IS_NOT_COMPLETED
Error code
Error message
Gone
Possible error codes: ERR_ENTITY_DELETED_PERMANENTLY
Error code
Error message
Request blocked by WAF
curl -X PATCH \
"https://{instance}.kiteworks.com/rest/mail/actions/deletePermanent?emailId:in=VALUE" \
-H "Authorization: Bearer YOUR_TOKEN"import requests
url = "https://{instance}.kiteworks.com/rest/mail/actions/deletePermanent"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
params = {
"emailId:in": "VALUE",
}
response = requests.patch(url, params=params, headers=headers)
print(response.json())Expand a distribution list
Resolves a distribution list email address and returns its members.
The email address to check or expand.
Indicates whether to include the email addresses of distribution list members.
If provided, the distribution list will include only members who have received this specific email.
Returns the distribution list with its resolved member email addresses.
Indicates whether the email belongs to a distribution list
List of members in the distribution list
Forbidden
Possible error codes: ERR_ACCESS_USER
Error code
Error message
Request blocked by WAF
curl -X GET \
"https://{instance}.kiteworks.com/rest/mail/actions/distributionList?email=VALUE" \
-H "Authorization: Bearer YOUR_TOKEN"import requests
url = "https://{instance}.kiteworks.com/rest/mail/actions/distributionList"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
params = {
"email": "VALUE",
}
response = requests.get(url, params=params, headers=headers)
print(response.json())Mark messages as read
Description:
Using email IDs, marks the specified messages as read in the current user's Inbox.Preconditions:
Must be the sender or a recipient of the messages.Response:
Returns a full or partial success response indicating which messages were marked as read.Comma-separated list of email IDs to be processed.
If set to true, the operation will continue for the valid items even if some items result in failure.
Email messages marked as read successfully.
Partially successful — some messages could not be marked as read.
Error code
Error message
Associated field, if applicable.
List of failed IDs.
List of succeeded IDs.
Unauthorized
Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED
Error code
Error message
Forbidden
Possible error codes: ERR_ACCESS_USER, ERR_ENTITY_DELETED
Error code
Error message
Request blocked by WAF
curl -X PATCH \
"https://{instance}.kiteworks.com/rest/mail/actions/read?emailId:in=VALUE" \
-H "Authorization: Bearer YOUR_TOKEN"import requests
url = "https://{instance}.kiteworks.com/rest/mail/actions/read"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
params = {
"emailId:in": "VALUE",
}
response = requests.patch(url, params=params, headers=headers)
print(response.json())Recover deleted messages
Description:
Using email IDs, recovers deleted messages from the current user's Trash folder and returns them to the Inbox.Preconditions:
Must be the sender or a recipient of the messages.Response:
Returns a full or partial success response indicating which messages were recovered to the Inbox.Comma-separated list of email IDs to be processed.
If set to true, the operation will continue for the valid items even if some items result in failure.
Messages recovered successfully.
Partially successful — some messages could not be recovered.
Error code
Error message
Associated field, if applicable.
List of failed IDs.
List of succeeded IDs.
Unauthorized
Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED
Error code
Error message
Forbidden
Possible error codes: ERR_ACCESS_USER, ERR_ENTITY_NOT_DELETED, ERR_ENTITY_EMAIL_IS_NOT_COMPLETED
Error code
Error message
Gone
Possible error codes: ERR_ENTITY_DELETED_PERMANENTLY
Error code
Error message
Request blocked by WAF
curl -X PATCH \
"https://{instance}.kiteworks.com/rest/mail/actions/recover?emailId:in=VALUE" \
-H "Authorization: Bearer YOUR_TOKEN"import requests
url = "https://{instance}.kiteworks.com/rest/mail/actions/recover"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
params = {
"emailId:in": "VALUE",
}
response = requests.patch(url, params=params, headers=headers)
print(response.json())Send files
Description:
Creates an email message and sends the specified file attachments through Kiteworks.Precondition:
Must be assigned a user profile with permission to send mail.Response:
Returns the created email and sends the file attachments to the specified recipients.If true, includes the entity in the response body.
Specifies additional fields to include in the response.
Determines the detail level of the response body.
List of recipients' email addresses (To field).
List of recipients' email addresses (CC field).
List of recipients' email addresses (BCC field).
List of file UUIDs to attach to the email.
Defines the access control level for the email.verify_recipient – Accessible only to specified recipients.no_auth – Public access, no authentication required.otp – Accessible to recipients; allows one-time passcode (OTP) via SMS for authentication.internal – Accessible to recipients and users within the organization.anyone_auth – Accessible to recipients and any authenticated user.email_otp – Accessible to recipients; allows one-time passcode (OTP) via email for authentication.
The expiration date of the email.
Indicates if the email is being saved as a draft.
Indicates if the email is a view-only version.
Text watermark applied to the email attachments (only applicable when preview is enabled).
If true, the email body is hidden from the notification email and is only visible to authenticated recipients when they open the secure link.
Indicates if the sender should receive a copy of the email.
If true, a cryptographic hash (fingerprint) of each attached file is included in the notification email, allowing recipients to verify file integrity.
The parent email ID used for email threading. Applicable only for forward or reply types.
(Deprecated) Send download notification to the sender. Use 'returnReceipts' instead.
List of recipients who should receive a download notification.
The type of email. Defaults to original.original – A new email.forward – Forwarding an existing email to new recipients.reply – A reply to an existing email.resend – Resending a previously sent email.
Indicates whether file upload is still in progress. Prevents sending if set to true.
The body content of the email.
The subject of the email (maximum length: 998 characters).
The web form ID associated with the email.
Custom web form fields associated with the email.
Indicates whether to send a notification email to the sender when the email expires.
UUID of the shared mailbox to send from. When set, the email is sent on behalf of the shared mailbox rather than the individual user.
List of email addresses to grant access to the email's download tracking dashboard.
Email created successfully.
Unique identifier of the email.
Unique identifier of the sender.
Unique identifier of the email template used.
Current status of the email (e.g., sent, draft, error, etc.).
Type of the email (e.g., original, reply, forward, etc.).
Date the email was last modified or sent.
Indicates if the email has been deleted.
Date when the email was withdrawn, if applicable.
Unique identifier of the associated email package.
Indicates whether the email is a view-only version, typically used for previewing attachments without enabling downloading.
Indicates whether the email was sent by the current user or another user.
Text watermark applied to the email attachments (applicable only for view-only version).
The variable name
The variable value
Unique identifier of the user associated with the recipient.
Recipient type.0 – To.1 – CC.2 – BCC.
Email address of the recipient.
Indicates if the recipient is a distribution list rather than an individual user.
Unique identifier (UUID) for the user.
Email address associated with the user.
Full name of the user.
URL or identifier for the user's profile icon.
Indicates if the email body is secured.
Date the email was last modified.
Unique identifier of the parent email, if applicable.
Unique identifier of the user who requested the return receipt.
Unique identifier (UUID) for the user.
Email address associated with the user.
Full name of the user.
URL or identifier for the user's profile icon.
Error message associated with the email, if any.
Subject line of the email.
Number of attachments in the email.
Expiration date of the email package, if applicable.
Antivirus (AV) scan status of the email.
Data Loss Prevention (DLP) scan status of the email.
Indicates if tracking access is enabled for the email.
Unique identifier of the user associated with the recipient.
Recipient type.0 – To.1 – CC.2 – BCC.
Email address of the recipient.
Indicates if the recipient is a distribution list rather than an individual user.
Unique identifier (UUID) for the user.
Email address associated with the user.
Full name of the user.
URL or identifier for the user's profile icon.
Indicates whether the recipient's tracking access has been revoked.
Indicates the restriction type applied to the email
Indicates if the email has been read.
The bucket where the email is stored. (e.g. inbox, sent, trash)
The body of the email.
Unique identifier of the email package.
Indicates whether the package includes a copy for the sender.
Indicates whether a fingerprint (hash) of the package should be included for verification.
Expiration time of the package in seconds from creation.
Count of the files attached to the package.
Indicates whether the package has been marked as deleted.
Access control list (ACL) associated with the package, specifying who can access it.
Unique identifier for the email package containing the attachment.
Unique identifier for the attachment.
Indicates whether the attachment has been withdrawn.
Name of the DRM-protected file.
Size of the DRM-protected file in bytes.
Access type for the attachment (e.g., read-only, editable).
Unique identifier (UUID) for the tag.
Display name of the tag.
Type category of the tag.
Unique identifier for the permission.
Name of the permission.
Indicates whether the permission is granted (True) or denied (False).
Unique identifier for the file associated with the attachment.
Name of the attachment file.
Size of the attachment file in bytes.
The MIME type of the attachment file.
Date when the attachment file was created.
Indicates if the attachment has been deleted.
A unique hash identifying the file version.
The algorithm used for generating the file version fingerprint. (e.g., sha3-256, md5).
The algorithm used to generate the fingerprint (e.g., sha3-256, md5).
The resulting hash value representing the fingerprint of the file or object.
Status of the attachment in the admin quarantine system.
Antivirus (AV) scan status of the attachment.
Data Loss Prevention (DLP) status of the attachment.
Link for accessing the email.
Raw email body content without HTML markup.
Headline or main title of the email.
Notice part of the email.
Full HTML body of the email.
The email address from which the email was sent.
Body content generated from the email template.
Unique identifier of the web form associated with the email.
Fields included in the associated web form with the mail.
Unique identifier (UUID) for the user.
Email address associated with the user.
Full name of the user.
URL or identifier for the user's profile icon.
Unique identifier of the shared mailbox, if applicable.
HTML version of the email body.
Unique identifier (UUID) for the user.
Email address associated with the user.
Full name of the user.
URL or identifier for the user's profile icon.
CSS styles applied for dark mode.
Indicates whether the email already exists in the system.
Unauthorized
Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED
Error code
Error message
Forbidden
Possible error codes: 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
Error code
Error message
Unprocessable Content
Possible error codes: ERR_INPUT_EXCEEDS_MAX_VALUE, ERR_INPUT_HYPERLINK, ERR_INPUT_INVALID_DATE, ERR_INPUT_PAST_DATE, ERR_INVALID_PARAMETER
Error code
Error message
Request blocked by WAF
curl -X POST \
"https://{instance}.kiteworks.com/rest/mail/actions/sendFile" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"to": [
"string"
],
"cc": [
"string"
],
"bcc": [
"string"
],
"files": [
"string"
],
"acl": "verify_recipient",
"expire": "2024-01-15"
}'import requests
url = "https://{instance}.kiteworks.com/rest/mail/actions/sendFile"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
"Content-Type": "application/json",
}
payload = {
"to": [
"string"
],
"cc": [
"string"
],
"bcc": [
"string"
],
"files": [
"string"
],
"acl": "verify_recipient",
"expire": "2024-01-15"
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())Move messages to Trash
Description:
Using email IDs, moves messages from the current user's Inbox and Sent folders to the Trash folder.Preconditions:
Must be the sender or a recipient of the messages.Response:
Returns a full or partial success response indicating which messages were moved to Trash.Comma-separated list of email IDs to be processed.
If set to true, the operation will continue for the valid items even if some items result in failure.
Messages moved to Trash successfully.
Partially successful — some messages could not be moved to Trash.
Error code
Error message
Associated field, if applicable.
List of failed IDs.
List of succeeded IDs.
Unauthorized
Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED
Error code
Error message
Forbidden
Possible error codes: ERR_ACCESS_USER, ERR_ENTITY_DELETED, ERR_ENTITY_EMAIL_IS_NOT_COMPLETED
Error code
Error message
Request blocked by WAF
curl -X PATCH \
"https://{instance}.kiteworks.com/rest/mail/actions/trash?emailId:in=VALUE" \
-H "Authorization: Bearer YOUR_TOKEN"import requests
url = "https://{instance}.kiteworks.com/rest/mail/actions/trash"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
params = {
"emailId:in": "VALUE",
}
response = requests.patch(url, params=params, headers=headers)
print(response.json())Mark messages as unread
Description:
Using email IDs, marks the specified messages as unread in the current user's Inbox.Preconditions:
Must be the sender or a recipient of the messages.Response:
Returns a full or partial success response indicating which messages were marked as unread.Comma-separated list of email IDs to be processed.
If set to true, the operation will continue for the valid items even if some items result in failure.
Email messages marked as unread successfully.
Partially successful — some messages could not be marked as unread.
Error code
Error message
Associated field, if applicable.
List of failed IDs.
List of succeeded IDs.
Unauthorized
Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED
Error code
Error message
Forbidden
Possible error codes: ERR_ACCESS_USER, ERR_ENTITY_DELETED
Error code
Error message
Request blocked by WAF
curl -X PATCH \
"https://{instance}.kiteworks.com/rest/mail/actions/unread?emailId:in=VALUE" \
-H "Authorization: Bearer YOUR_TOKEN"import requests
url = "https://{instance}.kiteworks.com/rest/mail/actions/unread"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
params = {
"emailId:in": "VALUE",
}
response = requests.patch(url, params=params, headers=headers)
print(response.json())Download email attachments in ZIP format
Using email IDs, downloads a set of email attachments in ZIP format from your Inbox and Sent folders.
The unique identifier of the email for downloading attachments as a ZIP file.
The unique identifier of the attachment.. Search for results that match any of the specified values for this parameter.
The name of the ZIP file.
The reference ID of the email (Mandatory if the email can be accessed without authentication).
The email address of the user requesting the file.
The user's timezone offset in seconds. For example, UTC+08:00 = 28800 seconds.
Determines the detail level of the response body.
Returns the selected email attachments as a ZIP archive.
Forbidden
Possible error codes: ERR_ACCESS_USER
Error code
Error message
Request blocked by WAF
curl -X GET \
"https://{instance}.kiteworks.com/rest/mail/:emailId/attachments/actions/zip?attachmentId:in=VALUE" \
-H "Authorization: Bearer YOUR_TOKEN"import requests
emailId = "VALUE" # The unique identifier of the email for downloading attachments as a ZIP file.
url = f"https://{{instance}}.kiteworks.com/rest/mail/{emailId}/attachments/actions/zip"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
params = {
"attachmentId:in": "VALUE",
}
response = requests.get(url, params=params, headers=headers)
print(response.json())Get email attachment security status
Using email IDs, gets the security scan results of email attachments in your Inbox and Sent folders, prior to downloading in ZIP format.
The unique identifier of the email.
The unique identifier of the attachment.. Search for results that match any of the specified values for this parameter.
The reference ID of the email (Mandatory if the email can be accessed without authentication).
Determines the detail level of the response body.
All specified attachments passed security checks and are safe to download. No content is returned.
Forbidden
Possible error codes: ERR_ACCESS_USER
Error code
Error message
Request blocked by WAF
curl -X GET \
"https://{instance}.kiteworks.com/rest/mail/:emailId/attachments/actions/zipStatus?attachmentId:in=VALUE" \
-H "Authorization: Bearer YOUR_TOKEN"import requests
emailId = "VALUE" # The unique identifier of the email.
url = f"https://{{instance}}.kiteworks.com/rest/mail/{emailId}/attachments/actions/zipStatus"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
params = {
"attachmentId:in": "VALUE",
}
response = requests.get(url, params=params, headers=headers)
print(response.json())Get email attachment download report
Returns a download tracking report for the specified email, listing all recorded download and interaction events for its attachments.
The unique identifier of the email.
Returns the download tracking report for the specified email.
Unix timestamp of when the event occurred.
The name of the event action (e.g. download_email, view_file, copy_file, file_withdrawn).
Email address of the user who performed the action.
Indicates whether the action was completed successfully.
Indicates whether the attachment was withdrawn at the time of the event.
The unique identifier of the attachment file. Present only when the event is associated with a specific file.
The name of the attachment file. Present only when the event is associated with a specific file.
A secondary classification of the event type. Present only when applicable.
Unix timestamp of when the email was sent.
Subject line of the email.
Forbidden
Possible error codes: ERR_ACCESS_USER
Error code
Error message
Request blocked by WAF
curl -X GET \
"https://{instance}.kiteworks.com/rest/mail/:emailId/attachments/report" \
-H "Authorization: Bearer YOUR_TOKEN"import requests
emailId = "VALUE" # The unique identifier of the email.
url = f"https://{{instance}}.kiteworks.com/rest/mail/{emailId}/attachments/report"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())Export email attachment download report as CSV
Generates a download tracking report for the specified email and returns it as a CSV file.
The unique identifier of the email.
Returns the download tracking report as a CSV file attachment.
Forbidden
Possible error codes: ERR_ACCESS_USER
Error code
Error message
Request blocked by WAF
curl -X GET \
"https://{instance}.kiteworks.com/rest/mail/:emailId/attachments/reportCsv" \
-H "Authorization: Bearer YOUR_TOKEN"import requests
emailId = "VALUE" # The unique identifier of the email.
url = f"https://{{instance}}.kiteworks.com/rest/mail/{emailId}/attachments/reportCsv"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())Download email attachment
Downloads the specified file attached to a message.
The unique identifier of the email containing the attachment.
The unique identifier of the attachment.
The reference code for the email. Required if the email can be accessed without authentication.
Determines the detail level of the response body.
Range of bytes to download. e.g. bytes=0-1024
Returns the binary content of the attachment file. Responds with HTTP 206 Partial Content when a Range header is included in the request.
Forbidden
Possible error codes: ERR_ACCESS_USER
Error code
Error message
Request blocked by WAF
curl -X GET \
"https://{instance}.kiteworks.com/rest/mail/:emailId/attachments/:id/content" \
-H "Authorization: Bearer YOUR_TOKEN"import requests
emailId = "VALUE" # The unique identifier of the email containing the attachment.
id = "VALUE" # The unique identifier of the attachment.
url = f"https://{{instance}}.kiteworks.com/rest/mail/{emailId}/attachments/{id}/content"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())Get email attachment preview metadata
Gets file preview metadata about an email attachment, such as the permalink for previewing the file and if the file contains a watermark. Must be assigned the view permission for the file.
The unique identifier of the email containing the attachment.
The unique identifier of the attachment.
The reference code for the email. Required if the email can be accessed without authentication.
Determines the detail level of the response body.
Returns the preview metadata for the specified attachment, including the URL to render the preview.
Preview link for the file
PDF file for the preview
URL for viewing the preview
Preview processing status. Accepted values: processing, preview, failed
Format of the generated preview, such as image or PDF
Additional metadata about the preview, such as dimensions or page count
MIME type of the preview file
Indicates whether the preview is a native render
Watermark applied to the preview
Original file extension for TDF files
Forbidden
Possible error codes: ERR_ACCESS_USER
Error code
Error message
Request blocked by WAF
curl -X GET \
"https://{instance}.kiteworks.com/rest/mail/:emailId/attachments/:id/preview" \
-H "Authorization: Bearer YOUR_TOKEN"import requests
emailId = "VALUE" # The unique identifier of the email containing the attachment.
id = "VALUE" # The unique identifier of the attachment.
url = f"https://{{instance}}.kiteworks.com/rest/mail/{emailId}/attachments/{id}/preview"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())Get email metadata
Description:
Gets the metadata for a specified email message, including subject, sender, recipients, sent date, and attachment details.Preconditions:
None.Response:
Returns the email metadata.The unique identifier (UUID) of the email.
If true, includes the entity in the response body.
Specifies additional fields to include in the response.
Determines the detail level of the response body.
The reference ID of the email (Mandatory if the email can be accessed without authentication).
Indicates whether the user clicked to print the email.
Email metadata returned successfully.
Unique identifier of the email.
Unique identifier of the sender.
Unique identifier of the email template used.
Current status of the email (e.g., sent, draft, error, etc.).
Type of the email (e.g., original, reply, forward, etc.).
Date the email was last modified or sent.
Indicates if the email has been deleted.
Date when the email was withdrawn, if applicable.
Unique identifier of the associated email package.
Indicates whether the email is a view-only version, typically used for previewing attachments without enabling downloading.
Indicates whether the email was sent by the current user or another user.
Text watermark applied to the email attachments (applicable only for view-only version).
The variable name
The variable value
Unique identifier of the user associated with the recipient.
Recipient type.0 – To.1 – CC.2 – BCC.
Email address of the recipient.
Indicates if the recipient is a distribution list rather than an individual user.
Unique identifier (UUID) for the user.
Email address associated with the user.
Full name of the user.
URL or identifier for the user's profile icon.
Indicates if the email body is secured.
Date the email was last modified.
Unique identifier of the parent email, if applicable.
Unique identifier of the user who requested the return receipt.
Unique identifier (UUID) for the user.
Email address associated with the user.
Full name of the user.
URL or identifier for the user's profile icon.
Error message associated with the email, if any.
Subject line of the email.
Number of attachments in the email.
Expiration date of the email package, if applicable.
Antivirus (AV) scan status of the email.
Data Loss Prevention (DLP) scan status of the email.
Indicates if tracking access is enabled for the email.
Unique identifier of the user associated with the recipient.
Recipient type.0 – To.1 – CC.2 – BCC.
Email address of the recipient.
Indicates if the recipient is a distribution list rather than an individual user.
Unique identifier (UUID) for the user.
Email address associated with the user.
Full name of the user.
URL or identifier for the user's profile icon.
Indicates whether the recipient's tracking access has been revoked.
Indicates the restriction type applied to the email
Indicates if the email has been read.
The bucket where the email is stored. (e.g. inbox, sent, trash)
The body of the email.
Unique identifier of the email package.
Indicates whether the package includes a copy for the sender.
Indicates whether a fingerprint (hash) of the package should be included for verification.
Expiration time of the package in seconds from creation.
Count of the files attached to the package.
Indicates whether the package has been marked as deleted.
Access control list (ACL) associated with the package, specifying who can access it.
Unique identifier for the email package containing the attachment.
Unique identifier for the attachment.
Indicates whether the attachment has been withdrawn.
Name of the DRM-protected file.
Size of the DRM-protected file in bytes.
Access type for the attachment (e.g., read-only, editable).
Unique identifier (UUID) for the tag.
Display name of the tag.
Type category of the tag.
Unique identifier for the permission.
Name of the permission.
Indicates whether the permission is granted (True) or denied (False).
Unique identifier for the file associated with the attachment.
Name of the attachment file.
Size of the attachment file in bytes.
The MIME type of the attachment file.
Date when the attachment file was created.
Indicates if the attachment has been deleted.
A unique hash identifying the file version.
The algorithm used for generating the file version fingerprint. (e.g., sha3-256, md5).
The algorithm used to generate the fingerprint (e.g., sha3-256, md5).
The resulting hash value representing the fingerprint of the file or object.
Status of the attachment in the admin quarantine system.
Antivirus (AV) scan status of the attachment.
Data Loss Prevention (DLP) status of the attachment.
Link for accessing the email.
Raw email body content without HTML markup.
Headline or main title of the email.
Notice part of the email.
Full HTML body of the email.
The email address from which the email was sent.
Body content generated from the email template.
Unique identifier of the web form associated with the email.
Fields included in the associated web form with the mail.
Unique identifier (UUID) for the user.
Email address associated with the user.
Full name of the user.
URL or identifier for the user's profile icon.
Unique identifier of the shared mailbox, if applicable.
HTML version of the email body.
Unique identifier (UUID) for the user.
Email address associated with the user.
Full name of the user.
URL or identifier for the user's profile icon.
CSS styles applied for dark mode.
Indicates whether the email already exists in the system.
Request blocked by WAF
curl -X GET \
"https://{instance}.kiteworks.com/rest/mail/:id" \
-H "Authorization: Bearer YOUR_TOKEN"import requests
id = "VALUE" # The unique identifier (UUID) of the email.
url = f"https://{{instance}}.kiteworks.com/rest/mail/{id}"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())Delete a draft message
Description:
Deletes a single message from the current user's Drafts folder.Preconditions:
None.Response:
Removes the draft message from the Drafts folder.The unique identifier (UUID) of the email.
Draft email deleted successfully.
Unauthorized
Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED
Error code
Error message
Forbidden
Possible error codes: ERR_ACCESS_NOT_SENDER, ERR_ACCESS_USER, ERR_ENTITY_EMAIL_IS_SENT, ERR_PROFILE_MAIL_DISABLED, ERR_ENTITY_DELETED
Error code
Error message
Request blocked by WAF
curl -X DELETE \
"https://{instance}.kiteworks.com/rest/mail/:id" \
-H "Authorization: Bearer YOUR_TOKEN"import requests
id = "VALUE" # The unique identifier (UUID) of the email.
url = f"https://{{instance}}.kiteworks.com/rest/mail/{id}"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.delete(url, headers=headers)
print(response.json())Update and send a draft message
Description:
Updates the content of an existing draft message and sends it to its recipients.Precondition:
Must be assigned a user profile with permission to send mail.Response:
Returns the updated email and sends the message to the specified recipients.The unique identifier (UUID) of the email.
If true, includes the entity in the response body.
Specifies additional fields to include in the response.
Determines the detail level of the response body.
List of recipients' email addresses (To field).
List of recipients' email addresses (CC field).
List of recipients' email addresses (BCC field).
List of file UUIDs to attach to the email.
Defines the access control level for the email.verify_recipient – Accessible only to specified recipients.no_auth – Public access, no authentication required.otp – Accessible to recipients; allows one-time passcode (OTP) via SMS for authentication.internal – Accessible to recipients and users within the organization.anyone_auth – Accessible to recipients and any authenticated user.email_otp – Accessible to recipients; allows one-time passcode (OTP) via email for authentication.
The expiration date of the email.
Indicates if the email is being saved as a draft.
Indicates if the email is a view-only version.
Text watermark applied to the email attachments (only applicable when preview is enabled).
If true, the email body is hidden from the notification email and is only visible to authenticated recipients when they open the secure link.
Indicates if the sender should receive a copy of the email.
If true, a cryptographic hash (fingerprint) of each attached file is included in the notification email, allowing recipients to verify file integrity.
The parent email ID used for email threading. Applicable only for forward or reply types.
(Deprecated) Send download notification to the sender. Use 'returnReceipts' instead.
List of recipients who should receive a download notification.
The type of email. Defaults to original.original – A new email.forward – Forwarding an existing email to new recipients.reply – A reply to an existing email.resend – Resending a previously sent email.
Indicates whether file upload is still in progress. Prevents sending if set to true.
The body content of the email.
The subject of the email (maximum length: 998 characters).
The web form ID associated with the email.
Custom web form fields associated with the email.
Indicates whether to send a notification email to the sender when the email expires.
UUID of the shared mailbox to send from. When set, the email is sent on behalf of the shared mailbox rather than the individual user.
List of email addresses to grant access to the email's download tracking dashboard.
Draft email updated and sent successfully.
Unique identifier of the email.
Unique identifier of the sender.
Unique identifier of the email template used.
Current status of the email (e.g., sent, draft, error, etc.).
Type of the email (e.g., original, reply, forward, etc.).
Date the email was last modified or sent.
Indicates if the email has been deleted.
Date when the email was withdrawn, if applicable.
Unique identifier of the associated email package.
Indicates whether the email is a view-only version, typically used for previewing attachments without enabling downloading.
Indicates whether the email was sent by the current user or another user.
Text watermark applied to the email attachments (applicable only for view-only version).
The variable name
The variable value
Unique identifier of the user associated with the recipient.
Recipient type.0 – To.1 – CC.2 – BCC.
Email address of the recipient.
Indicates if the recipient is a distribution list rather than an individual user.
Unique identifier (UUID) for the user.
Email address associated with the user.
Full name of the user.
URL or identifier for the user's profile icon.
Indicates if the email body is secured.
Date the email was last modified.
Unique identifier of the parent email, if applicable.
Unique identifier of the user who requested the return receipt.
Unique identifier (UUID) for the user.
Email address associated with the user.
Full name of the user.
URL or identifier for the user's profile icon.
Error message associated with the email, if any.
Subject line of the email.
Number of attachments in the email.
Expiration date of the email package, if applicable.
Antivirus (AV) scan status of the email.
Data Loss Prevention (DLP) scan status of the email.
Indicates if tracking access is enabled for the email.
Unique identifier of the user associated with the recipient.
Recipient type.0 – To.1 – CC.2 – BCC.
Email address of the recipient.
Indicates if the recipient is a distribution list rather than an individual user.
Unique identifier (UUID) for the user.
Email address associated with the user.
Full name of the user.
URL or identifier for the user's profile icon.
Indicates whether the recipient's tracking access has been revoked.
Indicates the restriction type applied to the email
Indicates if the email has been read.
The bucket where the email is stored. (e.g. inbox, sent, trash)
The body of the email.
Unique identifier of the email package.
Indicates whether the package includes a copy for the sender.
Indicates whether a fingerprint (hash) of the package should be included for verification.
Expiration time of the package in seconds from creation.
Count of the files attached to the package.
Indicates whether the package has been marked as deleted.
Access control list (ACL) associated with the package, specifying who can access it.
Unique identifier for the email package containing the attachment.
Unique identifier for the attachment.
Indicates whether the attachment has been withdrawn.
Name of the DRM-protected file.
Size of the DRM-protected file in bytes.
Access type for the attachment (e.g., read-only, editable).
Unique identifier (UUID) for the tag.
Display name of the tag.
Type category of the tag.
Unique identifier for the permission.
Name of the permission.
Indicates whether the permission is granted (True) or denied (False).
Unique identifier for the file associated with the attachment.
Name of the attachment file.
Size of the attachment file in bytes.
The MIME type of the attachment file.
Date when the attachment file was created.
Indicates if the attachment has been deleted.
A unique hash identifying the file version.
The algorithm used for generating the file version fingerprint. (e.g., sha3-256, md5).
The algorithm used to generate the fingerprint (e.g., sha3-256, md5).
The resulting hash value representing the fingerprint of the file or object.
Status of the attachment in the admin quarantine system.
Antivirus (AV) scan status of the attachment.
Data Loss Prevention (DLP) status of the attachment.
Link for accessing the email.
Raw email body content without HTML markup.
Headline or main title of the email.
Notice part of the email.
Full HTML body of the email.
The email address from which the email was sent.
Body content generated from the email template.
Unique identifier of the web form associated with the email.
Fields included in the associated web form with the mail.
Unique identifier (UUID) for the user.
Email address associated with the user.
Full name of the user.
URL or identifier for the user's profile icon.
Unique identifier of the shared mailbox, if applicable.
HTML version of the email body.
Unique identifier (UUID) for the user.
Email address associated with the user.
Full name of the user.
URL or identifier for the user's profile icon.
CSS styles applied for dark mode.
Indicates whether the email already exists in the system.
Unauthorized
Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED
Error code
Error message
Forbidden
Possible error codes: ERR_ACCESS_NOT_SENDER, ERR_ACCESS_USER, ERR_ENTITY_DELETED, ERR_ENTITY_EMAIL_NOT_DRAFT, 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
Error code
Error message
Unprocessable Content
Possible error codes: ERR_INPUT_EXCEEDS_MAX_VALUE, ERR_INPUT_HYPERLINK, ERR_INPUT_INVALID_DATE, ERR_INPUT_PAST_DATE, ERR_INVALID_PARAMETER, ERR_HEP_VALIDATION_BLOCK (raw validation service response when HEP policy blocks send)
Error code
Error message
Request blocked by WAF
curl -X PUT \
"https://{instance}.kiteworks.com/rest/mail/:id/actions/sendFile" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"to": [
"string"
],
"cc": [
"string"
],
"bcc": [
"string"
],
"files": [
"string"
],
"acl": "verify_recipient",
"expire": "2024-01-15"
}'import requests
id = "VALUE" # The unique identifier (UUID) of the email.
url = f"https://{{instance}}.kiteworks.com/rest/mail/{id}/actions/sendFile"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
"Content-Type": "application/json",
}
payload = {
"to": [
"string"
],
"cc": [
"string"
],
"bcc": [
"string"
],
"files": [
"string"
],
"acl": "verify_recipient",
"expire": "2024-01-15"
}
response = requests.put(url, headers=headers, json=payload)
print(response.json())Get attachments for an email message
Description:
Using an email ID, returns a paginated list of attachments for the specified message, including file metadata for each attachment.Preconditions:
Must be the sender or a recipient of the message.Response:
Returns the list of email attachments with metadata, including total count for pagination.The unique identifier (UUID) of the email.
Maximum number of attachments to return.
Number of attachments to skip before returning results, for pagination.
The reference ID of the email (Mandatory if the email can be accessed without authentication).
Email attachments returned successfully.
Unique identifier for the email package containing the attachment.
Unique identifier for the attachment.
Indicates whether the attachment has been withdrawn.
Name of the DRM-protected file.
Size of the DRM-protected file in bytes.
Access type for the attachment (e.g., read-only, editable).
Unique identifier (UUID) for the tag.
Display name of the tag.
Type category of the tag.
Unique identifier for the permission.
Name of the permission.
Indicates whether the permission is granted (True) or denied (False).
Unique identifier for the file associated with the attachment.
Name of the attachment file.
Size of the attachment file in bytes.
The MIME type of the attachment file.
Date when the attachment file was created.
Indicates if the attachment has been deleted.
A unique hash identifying the file version.
The algorithm used for generating the file version fingerprint. (e.g., sha3-256, md5).
The algorithm used to generate the fingerprint (e.g., sha3-256, md5).
The resulting hash value representing the fingerprint of the file or object.
Status of the attachment in the admin quarantine system.
Antivirus (AV) scan status of the attachment.
Data Loss Prevention (DLP) status of the attachment.
Total number of items available.
Maximum number of items returned per page.
Number of items skipped before the current page.
Unauthorized
Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED
Error code
Error message
Forbidden
Possible error codes: ERR_ACCESS_USER
Error code
Error message
Request blocked by WAF
curl -X GET \
"https://{instance}.kiteworks.com/rest/mail/:id/attachments" \
-H "Authorization: Bearer YOUR_TOKEN"import requests
id = "VALUE" # The unique identifier (UUID) of the email.
url = f"https://{{instance}}.kiteworks.com/rest/mail/{id}/attachments"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())Get an email attachment by attachment ID
Description:
Using a file attachment ID, returns the name and metadata for the specified attachment on a given message.Preconditions:
Must be the sender or a recipient of the message.Response:
Returns the attachment filename and associated metadata.The unique identifier (UUID) of the email.
The unique identifier (UUID) of the attachment.
The reference ID of the email (Mandatory if the email can be accessed without authentication).
Email attachment returned successfully.
Unique identifier for the email package containing the attachment.
Unique identifier for the attachment.
Indicates whether the attachment has been withdrawn.
Name of the DRM-protected file.
Size of the DRM-protected file in bytes.
Access type for the attachment (e.g., read-only, editable).
Unique identifier (UUID) for the tag.
Display name of the tag.
Type category of the tag.
Unique identifier for the permission.
Name of the permission.
Indicates whether the permission is granted (True) or denied (False).
Unique identifier for the file associated with the attachment.
Name of the attachment file.
Size of the attachment file in bytes.
The MIME type of the attachment file.
Date when the attachment file was created.
Indicates if the attachment has been deleted.
A unique hash identifying the file version.
The algorithm used for generating the file version fingerprint. (e.g., sha3-256, md5).
The algorithm used to generate the fingerprint (e.g., sha3-256, md5).
The resulting hash value representing the fingerprint of the file or object.
Status of the attachment in the admin quarantine system.
Antivirus (AV) scan status of the attachment.
Data Loss Prevention (DLP) status of the attachment.
Unauthorized
Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED
Error code
Error message
Forbidden
Possible error codes: ERR_ACCESS_USER
Error code
Error message
Request blocked by WAF
curl -X GET \
"https://{instance}.kiteworks.com/rest/mail/:id/attachments/:attachment_id" \
-H "Authorization: Bearer YOUR_TOKEN"import requests
id = "VALUE" # The unique identifier (UUID) of the email.
attachment_id = "VALUE" # The unique identifier (UUID) of the attachment.
url = f"https://{{instance}}.kiteworks.com/rest/mail/{id}/attachments/{attachment_id}"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())Get the package associated with an email
Description:
Returns the package associated with the specified email message.Preconditions:
Must have access to the specified email message.Response:
Returns the email package details.The unique identifier (UUID) of the email.
The reference ID of the email (Mandatory if the email can be accessed without authentication).
Email package returned successfully.
Unauthorized
Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED
Error code
Error message
Forbidden
Possible error codes: ERR_ACCESS_USER
Error code
Error message
Request blocked by WAF
curl -X GET \
"https://{instance}.kiteworks.com/rest/mail/:id/packages" \
-H "Authorization: Bearer YOUR_TOKEN"import requests
id = "VALUE" # The unique identifier (UUID) of the email.
url = f"https://{{instance}}.kiteworks.com/rest/mail/{id}/packages"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())Get email recipients
Description:
Gets a paginated list of recipient email addresses for the specified message.Preconditions:
Must be the sender or a recipient of the message.Response:
Returns the recipient email addresses and pagination metadata.The unique identifier (UUID) of the email.
If true, includes the entity in the response body.
Specifies additional fields to include in the response.
Determines the detail level of the response body.
The reference ID of the email (Mandatory if the email can be accessed without authentication).
Sort order for the recipient list. Default is type:asc.
Allowed values: id:asc, id:desc, type:asc, type:desc.
Filter recipients by type. Accepts a comma-separated list of integer values.0 – To.1 – CC.2 – BCC.
Range limit.
Range offset.
Email recipients returned successfully.
Unauthorized
Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED
Error code
Error message
Forbidden
Possible error codes: ERR_ACCESS_USER
Error code
Error message
Request blocked by WAF
curl -X GET \
"https://{instance}.kiteworks.com/rest/mail/:id/recipients" \
-H "Authorization: Bearer YOUR_TOKEN"import requests
id = "VALUE" # The unique identifier (UUID) of the email.
url = f"https://{{instance}}.kiteworks.com/rest/mail/{id}/recipients"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())Withdraw files from a sent message
Description:
Using an email ID, withdraws the specified file attachments from a sent message.Notes:
- The message itself is not withdrawn. Only the links to its file attachments are deactivated, making the files inaccessible to the original recipients. The files remain in the system until they expire.
- If a recipient forwarded the message before it was withdrawn, attachment links remain active for those recipients until the files expire.
Preconditions:
Must be the sender of the message.Response:
Deactivates download links for the specified email attachments.The unique identifier (UUID) of the email.
A comma-separated list of attachment IDs to be withdrawn.
The unique identifier of the Shared Mailbox. If provided, the operation will be performed within the specified Shared Mailbox context.
Attachments withdrawn successfully.
Unauthorized
Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED
Error code
Error message
Forbidden
Possible error codes: ERR_ACCESS_NOT_SENDER, ERR_ACCESS_USER, ERR_ENTITY_DELETED, ERR_ENTITY_IS_DELETED_ATTACHMENT
Error code
Error message
Unprocessable Content
Possible error codes: ERR_INVALID_PARAMETER
Error code
Error message
Request blocked by WAF
curl -X POST \
"https://{instance}.kiteworks.com/rest/mail/:id/actions/withdrawFiles?id:in=VALUE" \
-H "Authorization: Bearer YOUR_TOKEN"import requests
id = "VALUE" # The unique identifier (UUID) of the email.
url = f"https://{{instance}}.kiteworks.com/rest/mail/{id}/actions/withdrawFiles"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
params = {
"id:in": "VALUE",
}
response = requests.post(url, params=params, headers=headers)
print(response.json())Save email attachments to a Kiteworks folder
Description:
Saves one or more email attachments to a specified Kiteworks folder.Preconditions:
Must have the `file_copy` permission for the files being copied and `file_add` permission for the destination folder.Response:
Returns the saved files in the destination folder. If duplicate filenames exist, a number is appended to the saved file names to avoid conflicts.The unique identifier (UUID) of the email.
If true, includes the entity in the response body.
Specifies additional fields to include in the response.
Determines the detail level of the response body.
The ID of the destination folder where the item will be copied/moved.
If a file with the same name exists, create a new version instead of overwriting it. Default is True.
Attachment files copied successfully.
Unique identifier (UUID) of the file.
Unique identifier (UUID) of the parent folder.
Name of the object.
Type of the object.f – File.d – Folder.
Unique identifier (UUID) who created the file.
Unique identifier (UUID) for the user.
Email address associated with the user.
Full name of the user.
URL or identifier for the user's profile icon.
The date and time when the object was created.
The date and time when the object was last modified.
Expiration timestamp of the object, if applicable.
Unique identifier for the permission.
Name of the permission.
Indicates whether the permission is granted (True) or denied (False).
Indicates whether the object has been deleted.
Indicates whether the object has been permanently deleted.
Permanent URL link to access the file.
Path to the object in the hierarchy.
Unique identifier (UUID) of the associated object (file or folder).
Role assigned to the member.
Unique identifier (UUID) of the user.
Unique identifier of the LDAP group.
Unique identifier (UUID) for the user.
Email address associated with the user.
Full name of the user.
URL or identifier for the user's profile icon.
Role ID
Role name
Role rank
Role type
LDAP Group ID
LDAP Group name
LDAP Group domain name
LDAP Group email
LDAP Group description
Unique identifier (UUID) for the user.
Email address associated with the user.
Full name of the user.
URL or identifier for the user's profile icon.
Date when the file or folder was shared.
Inherited role ID from the parent folder, if applicable.
List of allowed folder role IDs.
Email associated with the member.
Rank of the member role.
Vendor document ID associated with the object.
Name of the vendor document associated with the object.
Indicates whether the folder or the parent folder containing the file is marked as secure.
ID representing the source of the object (1 - Salesforce, 2 - Teams).
Unique identifier (UUID) for the user.
Email address associated with the user.
Full name of the user.
URL or identifier for the user's profile icon.
The size of the file in bytes.
The MIME type of the file.
A unique hash identifying the file.
The algorithm used to generate the fingerprint (e.g., sha3-256, md5).
The resulting hash value representing the fingerprint of the file or object.
The date and time when the file was created on the client side.
The date and time when the file was last modified on the client side.
Indicates whether the expiration date for the file has been overridden.
Unique identifier (UUID) for the user.
Email address associated with the user.
Full name of the user.
URL or identifier for the user's profile icon.
The date and time when the file was shared.
Unique identifier (UUID) of the folder.
Unique identifier (UUID) of the parent object.
Name of the object.
Type of the object.f – File.d – Folder.
Unique identifier (UUID) who created the folder.
Unique identifier (UUID) for the user.
Email address associated with the user.
Full name of the user.
URL or identifier for the user's profile icon.
The date and time when the object was created.
The date and time when the object was last modified.
Expiration timestamp of the object, if applicable.
Unique identifier for the permission.
Name of the permission.
Indicates whether the permission is granted (True) or denied (False).
Indicates whether the object has been deleted.
Indicates whether the object has been permanently deleted.
Permanent URL link to access the object.
Path to the folder in the hierarchy.
Unique identifier (UUID) of the associated object (file or folder).
Role assigned to the member.
Unique identifier (UUID) of the user.
Unique identifier of the LDAP group.
Unique identifier (UUID) for the user.
Email address associated with the user.
Full name of the user.
URL or identifier for the user's profile icon.
Role ID
Role name
Role rank
Role type
LDAP Group ID
LDAP Group name
LDAP Group domain name
LDAP Group email
LDAP Group description
Unique identifier (UUID) for the user.
Email address associated with the user.
Full name of the user.
URL or identifier for the user's profile icon.
Date when the file or folder was shared.
Inherited role ID from the parent folder, if applicable.
List of allowed folder role IDs.
Email associated with the member.
Rank of the member role.
Vendor document ID associated with the object.
Name of the vendor document associated with the object.
Indicates whether the folder or the parent folder containing the file is marked as secure.
ID representing the source of the object (1 - Salesforce, 2 - Teams).
Indicates if the folder is shared with other users.
Indicates if the folder can be synced by Desktop Sync Client.
Time duration (in days) for which the files in this folder are kept after being added to the folder.
The description of the folder.
Indicates if the folder is marked as a favorite by the user.
The number of files that have been pushed to mobile apps in this folder.
Role ID
Role name
Role rank
Role type
The Antivirus (AV) status of the folder.
The Data Loss Prevention (DLP) status of the folder.
Total number of members who have access to this folder.
Total number of subfolders within this folder.
Total number of files within this folder.
The maximum expiration date allowed for files in this folder.
The maximum duration (in days) that files in this folder can be kept after being added to the folder.
Indicates if the folder is part of an LDAP group.
Indicates if this folder is a subfolder of the user's "My Folder".
A list of IDs representing the path of the folder within the folder hierarchy.
Indicates if this folder is a root folder.
The ID of the root folder if this is a subfolder.
Indicates if a folder quota is applied to this folder.
The storage quota for the folder (in bytes).
The total storage size used by the folder (in bytes).
The amount of free space available in the folder (in bytes).
Indicates if a folder inherits permissions from the parent folder
The ID of the original file if this one is a copy.
Indicates the file version's availability status based on Antivirus (AV) settings and whether it has been scanned or detected as infected.
Indicates the file version's availability status based on Data Loss Prevention (DLP) settings and whether it has been scanned or detected as infected.
Indicates the file version's availability status based on the administrator's quarantine status.
Indicates if the file is locked.
Unique identifier (UUID) for the user.
Email address associated with the user.
Full name of the user.
URL or identifier for the user's profile icon.
Indicates if the file is shared with other users.
Unique identifier (UUID) for the user.
Email address associated with the user.
Full name of the user.
URL or identifier for the user's profile icon.
Unique identifier (UUID) for the pushed object.
Unique identifier (UUID) for the user who pushed the object.
The date and time when the object was pushed.
Unique identifier (UUID) for the user.
Email address associated with the user.
Full name of the user.
URL or identifier for the user's profile icon.
A list of IDs representing the path of the file within the folder hierarchy.
The WOPI (Web Application Open Platform Interface) source URL for the mobile application.
Unique identifier of the user.
The WOPI service ID.
URI scheme used by the mobile application to handle the file.
Indicates the level of support the mobile app has for the URI scheme.
Indicates if the file has been pushed to a mobile app.
Unique identifier (UUID) for the tag.
Display name of the tag.
Type category of the tag.
Indicates if the file is locked through a SafeEdit session.
Unique identifier (UUID) for the user.
Email address associated with the user.
Full name of the user.
URL or identifier for the user's profile icon.
The total number of versions for the file.
Tracking identifier associated with the file upload.
Unauthorized
Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED
Error code
Error message
Forbidden
Possible error codes: ERR_ACCESS_NOT_SENDER, ERR_ACCESS_USER, ERR_ENTITY_DELETED, ERR_ENTITY_IS_BASE_DIR, ERR_ENTITY_IS_DELETED_ATTACHMENT, ERR_ENTITY_IS_MY_DIR, ERR_ENTITY_IS_SECURE_FOLDER, ERR_ENTITY_RESTRICTED_EXTENSION, ERR_ENTITY_RESTRICTED_TYPE
Error code
Error message
Unprocessable Content
Possible error codes: ERR_INVALID_PARAMETER
Error code
Error message
Request blocked by WAF
curl -X POST \
"https://{instance}.kiteworks.com/rest/mail/:id/actions/copy?id:in=VALUE" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"destinationFolderId": "string",
"addVersion": true
}'import requests
id = "VALUE" # The unique identifier (UUID) of the email.
url = f"https://{{instance}}.kiteworks.com/rest/mail/{id}/actions/copy"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
"Content-Type": "application/json",
}
params = {
"id:in": "VALUE",
}
payload = {
"destinationFolderId": "string",
"addVersion": true
}
response = requests.post(url, params=params, headers=headers, json=payload)
print(response.json())Send tracked activity report for a sent message
Description:
Generates and emails a tracked activity report for a sent message to the current user's Inbox.Preconditions:
Must be the sender of the message and have tracking access enabled.Response:
Sends the tracking report to the current user's Inbox.The unique identifier (UUID) of the email.
If true, includes the entity in the response body.
Specifies additional fields to include in the response.
Determines the detail level of the response body.
Tracking report sent successfully.
Unauthorized
Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED
Error code
Error message
Forbidden
Possible error codes: ERR_ACCESS_NOT_SENDER, ERR_ACCESS_USER
Error code
Error message
Request blocked by WAF
curl -X POST \
"https://{instance}.kiteworks.com/rest/mail/:id/actions/sendTrackingReport" \
-H "Authorization: Bearer YOUR_TOKEN"import requests
id = "VALUE" # The unique identifier (UUID) of the email.
url = f"https://{{instance}}.kiteworks.com/rest/mail/{id}/actions/sendTrackingReport"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.post(url, headers=headers)
print(response.json())Get email attachments sent by the current user
Description:
Using an email ID, gets a list of files attached to messages in the current user's Inbox or Drafts folder, including file metadata.Preconditions:
Messages must belong to the current user.Response:
Returns the list of email attachments with associated metadata.Sorting:
Sort string syntax `FIELD_NAME:ORDER`.ORDER can be asc or desc.
Sorting options:
| FIELD_NAME | Description |
|---|---|
| id | The mail ID |
| subject | The mail subject |
| sent_date | The date the mail was sent |
| modified_date | The date the mail was last modified |
| type | The mail type: sent, draft, or request |
| size | The file size |
Range limit.
Range offset.
Filters attachments to those belonging to emails in the specified bucket.inbox – Received emails.draft – Unsent draft emails.outgoing – Emails queued or in progress.sent – Successfully sent emails.trash – Deleted emails.
Sort order for the results. Default is id:desc.
Allowed values: id:asc, id:desc, subject:asc, subject:desc, sent_date:asc, sent_date:desc, modified_date:asc, modified_date:desc, type:asc, type:desc, size:asc, size:desc.
Email attachments returned successfully.
Subject line of the email containing this attachment.
Size of the attachment in bytes.
File name of the attachment.
Date and time when the email was sent.
Date and time when the attachment was last modified.
Unique identifier (UUID) of the attachment.
MIME type of the attachment.
Identifier of the web form associated with the attachment, if any.
Type of the attachment.
Total number of items available.
Maximum number of items returned per page.
Number of items skipped before the current page.
Unauthorized
Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED
Error code
Error message
Request blocked by WAF
curl -X GET \
"https://{instance}.kiteworks.com/rest/mail/attachments" \
-H "Authorization: Bearer YOUR_TOKEN"import requests
url = "https://{instance}.kiteworks.com/rest/mail/attachments"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())Withdraw multiple files from messages in Sent and Drafts folders
Description:
Using attachment IDs, withdraws the specified attachments from messages in the current user's Sent and Drafts folders.Notes:
- The message itself is not withdrawn. Only the links to its file attachments are deactivated, making the files inaccessible to the original recipients. The files remain in the system until they expire.
- If a recipient forwarded the message before it was withdrawn, attachment links remain active for those recipients until the files expire.
Preconditions:
Must be the sender of the messages.Response:
Deactivates download links for the specified attachments across all matching Sent and Draft messages.Specified attachments withdrawn successfully.
Unauthorized
Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED
Error code
Error message
Unprocessable Content
Possible error codes: ERR_INVALID_PARAMETER
Error code
Error message
Request blocked by WAF
curl -X DELETE \
"https://{instance}.kiteworks.com/rest/mail/attachments?id:in=VALUE" \
-H "Authorization: Bearer YOUR_TOKEN"import requests
url = "https://{instance}.kiteworks.com/rest/mail/attachments"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
params = {
"id:in": "VALUE",
}
response = requests.delete(url, params=params, headers=headers)
print(response.json())Withdraw messages from Sent and Drafts folders
Description:
Using email IDs, withdraws messages from the current user's Sent and Drafts folders.Notes:
- The messages themselves are not withdrawn. Only the links to their file attachments are deactivated, making the files inaccessible to the original recipients. The files remain in the system until they expire.
- If a recipient forwarded a message before it was withdrawn, attachment links remain active for those recipients until the files expire.
Preconditions:
Must be the sender of the messages.Response:
Deactivates download links for attachments in the specified messages.List of email UUIDs to withdraw. Withdrawing an email revokes recipient access to its attachments.
Email messages withdrawn successfully.
Partially successful — some messages could not be withdrawn.
Error code
Error message
Associated field, if applicable.
List of failed IDs.
List of succeeded IDs.
Unauthorized
Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED
Error code
Error message
Forbidden
Possible error codes: ERR_ACCESS_USER, ERR_ENTITY_DELETED, ERR_ENTITY_EMAIL_IS_NOT_COMPLETED, ERR_ACCESS_NOT_SENDER, ERR_MAIL_BODY_UNSECURED, ERR_ENTITY_IS_EMAIL_CONTENT
Error code
Error message
Request blocked by WAF
curl -X POST \
"https://{instance}.kiteworks.com/rest/mail/actions/withdraw" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"ids": [
"string"
]
}'import requests
url = "https://{instance}.kiteworks.com/rest/mail/actions/withdraw"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
"Content-Type": "application/json",
}
payload = {
"ids": [
"string"
]
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())Get email message security scan status
Description:
Gets the security scan results for a mail message. Depending on system scan policies, message content and attachments may be scanned for antivirus threats, data loss prevention (DLP) violations, and advanced threat protection (ATP).Preconditions:
Must be the sender or a recipient of the message.Response:
Returns the security scan status for the message and its attachments.The unique identifier (UUID) of the email.
Message and attachments (if any) have passed all security scans successfully.
Unauthorized
Possible error codes: ERR_AUTH_UNAUTHORIZED
Error code
Error message
Forbidden
Possible error codes: ERR_ACCESS_USER, ERR_ENTITY_EMAIL_IS_DRAFT, ERR_ENTITY_EMAIL_SCANNING, ERR_ENTITY_EMAIL_SCANNING_DISALLOWED
Error code
Error message
Request blocked by WAF
curl -X GET \
"https://{instance}.kiteworks.com/rest/mail/:id/scanStatus" \
-H "Authorization: Bearer YOUR_TOKEN"import requests
id = "VALUE" # The unique identifier (UUID) of the email.
url = f"https://{{instance}}.kiteworks.com/rest/mail/{id}/scanStatus"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())Remove message tracking access
Description:
Removes the current user's access to tracking activity on a specified message.Preconditions:
Must be a recipient of the email and have tracking access.Response:
Revokes the current user's tracking access for the specified message.The unique identifier (UUID) of the email.
Email tracking access removed successfully.
Unauthorized
Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED
Error code
Error message
Forbidden
Possible error codes: ERR_ACCESS_USER, ERR_ENTITY_DELETED
Error code
Error message
Request blocked by WAF
curl -X DELETE \
"https://{instance}.kiteworks.com/rest/mail/:id/trackings/me" \
-H "Authorization: Bearer YOUR_TOKEN"import requests
id = "VALUE" # The unique identifier (UUID) of the email.
url = f"https://{{instance}}.kiteworks.com/rest/mail/{id}/trackings/me"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.delete(url, headers=headers)
print(response.json())Update message tracking access
Description:
Updates the tracking access settings for a sent message, adding or removing tracking permissions for specified users.Preconditions:
Must be the sender of the message and have tracking access enabled.Response:
Returns a confirmation that tracking access has been updated for the specified users.The unique identifier (UUID) of the email.
List of email addresses to grant access to the email's download tracking dashboard.
Mail tracking settings updated successfully.
Unauthorized
Possible error codes: ERR_AUTH_UNAUTHORIZED
Error code
Error message
Forbidden
Possible error codes: ERR_ACCESS_USER, ERR_NOT_INTERNAL_DOMAIN, ERR_INSUFFICIENT_TRACKING_PERMISSIONS
Error code
Error message
Request blocked by WAF
curl -X PUT \
"https://{instance}.kiteworks.com/rest/mail/:id/settings" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"trackingAccess": [
"string"
]
}'import requests
id = "VALUE" # The unique identifier (UUID) of the email.
url = f"https://{{instance}}.kiteworks.com/rest/mail/{id}/settings"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
"Content-Type": "application/json",
}
payload = {
"trackingAccess": [
"string"
]
}
response = requests.put(url, headers=headers, json=payload)
print(response.json())