# Kiteworks API — mail Operations
**32 endpoints** | [Browse interactive reference](https://developer.kiteworks.com/api-reference/mail.html) | [Download spec slice](https://developer.kiteworks.com/assets/specs/mail.json)
> **Authentication required.** All requests must include a Bearer access token in the
> `Authorization` header. See [Authentication](https://developer.kiteworks.com/authentication.md) for how to
> obtain a token using OAuth 2.0 Authorization Code (PKCE) or JWT Bearer flow.
---
## GET /rest/mail
**Summary:** 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 |
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `returnEntity` | query | no | If true, includes the entity in the response body. |
| `with` | query | no | Specifies additional fields to include in the response. |
| `mode` | query | no | Determines the detail level of the response body. |
| `senderId` | query | no | Unique identifier of the user who sent the email. |
| `senderId:in` | query | no | 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) |
| `isRecipient` | query | no | Filter results to include only emails where the current user is a recipient. |
| `read` | query | no | Filter results based on whether the email has been read by the current user. |
| `date` | query | no | Filter results by the email creation date. |
| `date:gt` | query | no | Filter emails created after the specified date. |
| `date:gte` | query | no | Filter emails created on or after the specified date. |
| `date:lt` | query | no | Filter emails created before the specified date. |
| `date:lte` | query | no | Filter emails created on or before the specified date. |
| `modified_date` | query | no | Filter emails by the last modified date of the email. |
| `modified_date:gt` | query | no | Filter emails modified after the specified date. |
| `modified_date:gte` | query | no | Filter emails modified on or after the specified date. |
| `modified_date:lt` | query | no | Filter emails modified before the specified date. |
| `modified_date:lte` | query | no | Filter emails modified on or before the specified date. |
| `deleted` | query | no | Indicates whether the email has been deleted. |
| `emailPackageId` | query | no | Filter results by the unique identifier of the email package. |
| `emailPackageId:in` | query | no | Filter results by email package identifiers. Matches any of the specified values. |
| `templateId` | query | no | Filter results by the unique identifier of the email template. |
| `templateId:in` | query | no | Filter results by email template identifiers. Matches any of the specified values. |
| `status` | query | no | 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. |
| `isPreview` | query | no | Filter results to include only preview emails if set to true. |
| `isUserSent` | query | no | Filter results to include only emails sent by the user if set to true. |
| `bucket` | query | no | 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. |
| `returnCustomWebForm` | query | no | Includes emails with custom web forms in the results. |
| `customWebFormOnly` | query | no | Filter results to only include emails with custom web forms. |
| `trackingOnly` | query | no | Filter results to only include emails with tracking access. |
| `approvalRequestOnly` | query | no | Filter results to only include emails with approval requests. |
| `webFormId` | query | no | Filter results by unique identifier of the email web form. |
| `orderBy` | query | no | Sort order for the results. Default is `id:asc`. Allowed values: `id:asc`, `id:desc`, `date:asc`, `date:desc`, `status:asc`, `status:desc`. |
| `sharedMailboxId` | query | no | Unique identifier of the shared mailbox. Filters results to emails belonging to the shared mailbox. |
| `limit` | query | no | Range limit. |
| `offset` | query | no | Range offset. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | Messages returned successfully. |
| 490 | Request blocked by WAF |
**Code Samples:**
**cURL:**
```shell
curl -X GET \
"https://{instance}.kiteworks.com/rest/mail" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
import requests
url = "https://{instance}.kiteworks.com/rest/mail"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
```
---
## DELETE /rest/mail
**Summary:** 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.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `emailId:in` | query | yes | Comma-separated list of email IDs to be processed. |
| `partialSuccess` | query | no | If set to `true`, the operation will continue for the valid items even if some items result in failure. |
**Responses:**
| Code | Description |
|------|-------------|
| 204 | Email messages deleted successfully. |
| 207 | Some email messages were deleted successfully while others failed. |
| 401 | Unauthorized Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED |
| 403 | Forbidden Possible error codes: ERR_ACCESS_NOT_SENDER, ERR_ACCESS_USER, ERR_ENTITY_EMAIL_IS_SENT, ERR_PROFILE_MAIL_DISABLED, ERR_ENTITY_DELETED |
| 490 | Request blocked by WAF |
**Response Examples:**
**401 (ERR_AUTH_INVALID_CSRF):**
```json
{
"errors": [
{
"code": "ERR_AUTH_INVALID_CSRF",
"message": "Invalid CSRF Authentication"
}
]
}
```
**401 (ERR_AUTH_UNAUTHORIZED):**
```json
{
"errors": [
{
"code": "ERR_AUTH_UNAUTHORIZED",
"message": "Unauthorized"
}
]
}
```
**403 (ERR_ACCESS_NOT_SENDER):**
```json
{
"errors": [
{
"code": "ERR_ACCESS_NOT_SENDER",
"message": "Authenticated user is not the sender of the specified email"
}
]
}
```
**403 (ERR_ACCESS_USER):**
```json
{
"errors": [
{
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
]
}
```
**403 (ERR_ENTITY_EMAIL_IS_SENT):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_EMAIL_IS_SENT",
"message": "Email can no longer be deleted"
}
]
}
```
**403 (ERR_PROFILE_MAIL_DISABLED):**
```json
{
"errors": [
{
"code": "ERR_PROFILE_MAIL_DISABLED",
"message": "User's profile has no mail access"
}
]
}
```
**403 (ERR_ENTITY_DELETED):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_DELETED",
"message": "Entity is deleted"
}
]
}
```
**Code Samples:**
**cURL:**
```shell
curl -X DELETE \
"https://{instance}.kiteworks.com/rest/mail?emailId:in=VALUE" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
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 /rest/mail/actions/counters
**Summary:** 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.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `returnCustomWebForm` | query | no | Indicates whether to include emails with custom web forms in the result. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | Message counts returned successfully. |
| 401 | Unauthorized Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED |
| 490 | Request blocked by WAF |
**Response Examples:**
**401 (ERR_AUTH_INVALID_CSRF):**
```json
{
"errors": [
{
"code": "ERR_AUTH_INVALID_CSRF",
"message": "Invalid CSRF Authentication"
}
]
}
```
**401 (ERR_AUTH_UNAUTHORIZED):**
```json
{
"errors": [
{
"code": "ERR_AUTH_UNAUTHORIZED",
"message": "Unauthorized"
}
]
}
```
**Code Samples:**
**cURL:**
```shell
curl -X GET \
"https://{instance}.kiteworks.com/rest/mail/actions/counters" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
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())
```
---
## PATCH /rest/mail/actions/deletePermanent
**Summary:** 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.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `emailId:in` | query | yes | Comma-separated list of email IDs to be processed. |
| `partialSuccess` | query | no | If set to `true`, the operation will continue for the valid items even if some items result in failure. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | Messages permanently deleted successfully. |
| 207 | Partially successful — some messages could not be permanently deleted. |
| 401 | Unauthorized Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED |
| 403 | Forbidden Possible error codes: ERR_ACCESS_USER, ERR_ENTITY_NOT_DELETED, ERR_ENTITY_EMAIL_IS_NOT_COMPLETED |
| 410 | Gone Possible error codes: ERR_ENTITY_DELETED_PERMANENTLY |
| 490 | Request blocked by WAF |
**Response Examples:**
**401 (ERR_AUTH_INVALID_CSRF):**
```json
{
"errors": [
{
"code": "ERR_AUTH_INVALID_CSRF",
"message": "Invalid CSRF Authentication"
}
]
}
```
**401 (ERR_AUTH_UNAUTHORIZED):**
```json
{
"errors": [
{
"code": "ERR_AUTH_UNAUTHORIZED",
"message": "Unauthorized"
}
]
}
```
**403 (ERR_ACCESS_USER):**
```json
{
"errors": [
{
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
]
}
```
**403 (ERR_ENTITY_NOT_DELETED):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_NOT_DELETED",
"message": "Entity is not deleted"
}
]
}
```
**403 (ERR_ENTITY_EMAIL_IS_NOT_COMPLETED):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_EMAIL_IS_NOT_COMPLETED",
"message": "Email is not completed"
}
]
}
```
**410 (ERR_ENTITY_DELETED_PERMANENTLY):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_DELETED_PERMANENTLY",
"message": "Entity is deleted permanently"
}
]
}
```
**Code Samples:**
**cURL:**
```shell
curl -X PATCH \
"https://{instance}.kiteworks.com/rest/mail/actions/deletePermanent?emailId:in=VALUE" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
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())
```
---
## GET /rest/mail/actions/distributionList
**Summary:** Expand a distribution list
Resolves a distribution list email address and returns its members.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `email` | query | yes | The email address to check or expand. |
| `expand` | query | no | Indicates whether to include the email addresses of distribution list members. |
| `emailId` | query | no | If provided, the distribution list will include only members who have received this specific email. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | Returns the distribution list with its resolved member email addresses. |
| 403 | Forbidden Possible error codes: ERR_ACCESS_USER |
| 490 | Request blocked by WAF |
**Response Examples:**
**200 (DistributionListExpanded):**
```json
{
"isDistributionList": true,
"members": [
"engineering@example.com",
"design@example.com"
]
}
```
**403 (ERR_ACCESS_USER):**
```json
{
"errors": {
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
}
```
**Code Samples:**
**cURL:**
```shell
curl -X GET \
"https://{instance}.kiteworks.com/rest/mail/actions/distributionList?email=VALUE" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
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())
```
---
## PATCH /rest/mail/actions/read
**Summary:** 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.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `emailId:in` | query | yes | Comma-separated list of email IDs to be processed. |
| `partialSuccess` | query | no | If set to `true`, the operation will continue for the valid items even if some items result in failure. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | Email messages marked as read successfully. |
| 207 | Partially successful — some messages could not be marked as read. |
| 401 | Unauthorized Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED |
| 403 | Forbidden Possible error codes: ERR_ACCESS_USER, ERR_ENTITY_DELETED |
| 490 | Request blocked by WAF |
**Response Examples:**
**401 (ERR_AUTH_INVALID_CSRF):**
```json
{
"errors": [
{
"code": "ERR_AUTH_INVALID_CSRF",
"message": "Invalid CSRF Authentication"
}
]
}
```
**401 (ERR_AUTH_UNAUTHORIZED):**
```json
{
"errors": [
{
"code": "ERR_AUTH_UNAUTHORIZED",
"message": "Unauthorized"
}
]
}
```
**403 (ERR_ACCESS_USER):**
```json
{
"errors": [
{
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
]
}
```
**403 (ERR_ENTITY_DELETED):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_DELETED",
"message": "Entity is deleted"
}
]
}
```
**Code Samples:**
**cURL:**
```shell
curl -X PATCH \
"https://{instance}.kiteworks.com/rest/mail/actions/read?emailId:in=VALUE" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
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())
```
---
## PATCH /rest/mail/actions/recover
**Summary:** 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.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `emailId:in` | query | yes | Comma-separated list of email IDs to be processed. |
| `partialSuccess` | query | no | If set to `true`, the operation will continue for the valid items even if some items result in failure. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | Messages recovered successfully. |
| 207 | Partially successful — some messages could not be recovered. |
| 401 | Unauthorized Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED |
| 403 | Forbidden Possible error codes: ERR_ACCESS_USER, ERR_ENTITY_NOT_DELETED, ERR_ENTITY_EMAIL_IS_NOT_COMPLETED |
| 410 | Gone Possible error codes: ERR_ENTITY_DELETED_PERMANENTLY |
| 490 | Request blocked by WAF |
**Response Examples:**
**401 (ERR_AUTH_INVALID_CSRF):**
```json
{
"errors": [
{
"code": "ERR_AUTH_INVALID_CSRF",
"message": "Invalid CSRF Authentication"
}
]
}
```
**401 (ERR_AUTH_UNAUTHORIZED):**
```json
{
"errors": [
{
"code": "ERR_AUTH_UNAUTHORIZED",
"message": "Unauthorized"
}
]
}
```
**403 (ERR_ACCESS_USER):**
```json
{
"errors": [
{
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
]
}
```
**403 (ERR_ENTITY_NOT_DELETED):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_NOT_DELETED",
"message": "Entity is not deleted"
}
]
}
```
**403 (ERR_ENTITY_EMAIL_IS_NOT_COMPLETED):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_EMAIL_IS_NOT_COMPLETED",
"message": "Email is not completed"
}
]
}
```
**410 (ERR_ENTITY_DELETED_PERMANENTLY):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_DELETED_PERMANENTLY",
"message": "Entity is deleted permanently"
}
]
}
```
**Code Samples:**
**cURL:**
```shell
curl -X PATCH \
"https://{instance}.kiteworks.com/rest/mail/actions/recover?emailId:in=VALUE" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
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())
```
---
## POST /rest/mail/actions/sendFile
**Summary:** 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.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `returnEntity` | query | no | If true, includes the entity in the response body. |
| `with` | query | no | Specifies additional fields to include in the response. |
| `mode` | query | no | Determines the detail level of the response body. |
**Request Body:**
| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `to` | string[] | no | List of recipients' email addresses (To field). |
| `cc` | string[] | no | List of recipients' email addresses (CC field). |
| `bcc` | string[] | no | List of recipients' email addresses (BCC field). |
| `files` | string[] | no | List of file UUIDs to attach to the email. |
| `acl` | string | no | 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. |
| `expire` | string | no | The expiration date of the email. |
| `draft` | boolean | no | Indicates if the email is being saved as a draft. |
| `preview` | boolean | no | Indicates if the email is a view-only version. |
| `watermark` | string | no | Text watermark applied to the email attachments (only applicable when `preview` is enabled). |
| `secureBody` | boolean | no | If true, the email body is hidden from the notification email and is only visible to authenticated recipients when they open the secure link. |
| `selfCopy` | boolean | no | Indicates if the sender should receive a copy of the email. |
| `includeFingerprint` | boolean | no | If true, a cryptographic hash (fingerprint) of each attached file is included in the notification email, allowing recipients to verify file integrity. |
| `parentEmailId` | string | no | The parent email ID used for email threading. Applicable only for `forward` or `reply` types. |
| `isSelfReturnReceipt` | boolean | no | (Deprecated) Send download notification to the sender. Use 'returnReceipts' instead. |
| `returnReceipts` | string[] | no | List of recipients who should receive a download notification. |
| `type` | string | no | 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. |
| `uploading` | boolean | no | Indicates whether file upload is still in progress. Prevents sending if set to `true`. |
| `body` | string | no | The body content of the email. |
| `subject` | string | no | The subject of the email (maximum length: 998 characters). |
| `webFormId` | string | no | The web form ID associated with the email. |
| `webFormFields` | object | no | Custom web form fields associated with the email. |
| `notifyExpired` | boolean | no | Indicates whether to send a notification email to the sender when the email expires. |
| `sharedMailboxId` | string | no | 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. |
| `trackingAccess` | string[] | no | List of email addresses to grant access to the email's download tracking dashboard. |
**Responses:**
| Code | Description |
|------|-------------|
| 201 | Email created successfully. |
| 401 | Unauthorized Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED |
| 403 | 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 |
| 422 | Unprocessable Content Possible error codes: ERR_INPUT_EXCEEDS_MAX_VALUE, ERR_INPUT_HYPERLINK, ERR_INPUT_INVALID_DATE, ERR_INPUT_PAST_DATE, ERR_INVALID_PARAMETER |
| 490 | Request blocked by WAF |
**Response Examples:**
**401 (ERR_AUTH_INVALID_CSRF):**
```json
{
"errors": [
{
"code": "ERR_AUTH_INVALID_CSRF",
"message": "Invalid CSRF Authentication"
}
]
}
```
**401 (ERR_AUTH_UNAUTHORIZED):**
```json
{
"errors": [
{
"code": "ERR_AUTH_UNAUTHORIZED",
"message": "Unauthorized"
}
]
}
```
**403 (ERR_ACCESS_USER):**
```json
{
"errors": [
{
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
]
}
```
**403 (ERR_ENTITY_DELETED):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_DELETED",
"message": "Entity is deleted"
}
]
}
```
**403 (ERR_ENTITY_IS_DELETED_ATTACHMENT):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_IS_DELETED_ATTACHMENT",
"message": "Requested Attachment(s) is deleted"
}
]
}
```
**403 (ERR_ENTITY_IS_SECURE_FOLDER):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_IS_SECURE_FOLDER",
"message": "Operation not permitted on restricted Folder."
}
]
}
```
**403 (ERR_INPUT_EMAIL_WITH_NO_RECIPIENTS_NOT_ALLOWED):**
```json
{
"errors": [
{
"code": "ERR_INPUT_EMAIL_WITH_NO_RECIPIENTS_NOT_ALLOWED",
"message": "The mail cannot be sent without any recipients"
}
]
}
```
**403 (ERR_INPUT_SECURE_BODY_WITH_NO_AUTH_NOT_ALLOWED):**
```json
{
"errors": [
{
"code": "ERR_INPUT_SECURE_BODY_WITH_NO_AUTH_NOT_ALLOWED",
"message": "Email message body cannot be secured if email does not require authentication"
}
]
}
```
**403 (ERR_PROFILE_INCLUDE_FINGERPRINT_DISABLED):**
```json
{
"errors": [
{
"code": "ERR_PROFILE_INCLUDE_FINGERPRINT_DISABLED",
"message": "This profile is not allowed to include fingerprint with sent files"
}
]
}
```
**403 (ERR_PROFILE_INCLUDE_FINGERPRINT_ENABLED):**
```json
{
"errors": [
{
"code": "ERR_PROFILE_INCLUDE_FINGERPRINT_ENABLED",
"message": "This profile cannot disable including fingerprint with sent files"
}
]
}
```
**403 (ERR_PROFILE_RETURN_RECEIPT_DISABLED):**
```json
{
"errors": [
{
"code": "ERR_PROFILE_RETURN_RECEIPT_DISABLED",
"message": "This profile is not allowed to set receipt notification with sent files"
}
]
}
```
**403 (ERR_PROFILE_RETURN_RECEIPT_ENABLED):**
```json
{
"errors": [
{
"code": "ERR_PROFILE_RETURN_RECEIPT_ENABLED",
"message": "This profile cannot disable return receipt notification with sent files"
}
]
}
```
**403 (ERR_PROFILE_SECURE_EMAIL_DISABLED):**
```json
{
"errors": [
{
"code": "ERR_PROFILE_SECURE_EMAIL_DISABLED",
"message": "This profile is not allowed to send secure emails"
}
]
}
```
**403 (ERR_PROFILE_SELF_COPY_DISABLED):**
```json
{
"errors": [
{
"code": "ERR_PROFILE_SELF_COPY_DISABLED",
"message": "This profile is not allowed to send copy to self"
}
]
}
```
**403 (ERR_PROFILE_SELF_COPY_ENABLED):**
```json
{
"errors": [
{
"code": "ERR_PROFILE_SELF_COPY_ENABLED",
"message": "Cannot disable self copy for this profile"
}
]
}
```
**403 (ERR_PROFILE_SEND_FILE_EXTERNAL_DISABLED):**
```json
{
"errors": [
{
"code": "ERR_PROFILE_SEND_FILE_EXTERNAL_DISABLED",
"message": "This profile is not allowed to send files to external users"
}
]
}
```
**403 (ERR_USER_HAS_NO_USER_TYPE):**
```json
{
"errors": [
{
"code": "ERR_USER_HAS_NO_USER_TYPE",
"message": "User has no profile"
}
]
}
```
**403 (ERR_USER_TYPE_NO_ACCESS):**
```json
{
"errors": [
{
"code": "ERR_USER_TYPE_NO_ACCESS",
"message": "Permission denied"
}
]
}
```
**422 (ERR_INPUT_EXCEEDS_MAX_VALUE):**
```json
{
"errors": [
{
"code": "ERR_INPUT_EXCEEDS_MAX_VALUE",
"message": "Field value exceeds maximum allowed value"
}
]
}
```
**422 (ERR_INPUT_HYPERLINK):**
```json
{
"errors": [
{
"code": "ERR_INPUT_HYPERLINK",
"message": "Not allowed hyperlink domain. Hyperlink domain should not different from anchored text domain."
}
]
}
```
**422 (ERR_INPUT_INVALID_DATE):**
```json
{
"errors": [
{
"code": "ERR_INPUT_INVALID_DATE",
"message": "The input is not a valid date."
}
]
}
```
**422 (ERR_INPUT_PAST_DATE):**
```json
{
"errors": [
{
"code": "ERR_INPUT_PAST_DATE",
"message": "Field value should be future date"
}
]
}
```
**422 (ERR_INVALID_PARAMETER):**
```json
{
"errors": [
{
"code": "ERR_INVALID_PARAMETER",
"message": "Invalid Parameter Exception"
}
]
}
```
**Code Samples:**
**cURL:**
```shell
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"
}'
```
**Python:**
```python
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())
```
---
## PATCH /rest/mail/actions/trash
**Summary:** 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.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `emailId:in` | query | yes | Comma-separated list of email IDs to be processed. |
| `partialSuccess` | query | no | If set to `true`, the operation will continue for the valid items even if some items result in failure. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | Messages moved to Trash successfully. |
| 207 | Partially successful — some messages could not be moved to Trash. |
| 401 | Unauthorized Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED |
| 403 | Forbidden Possible error codes: ERR_ACCESS_USER, ERR_ENTITY_DELETED, ERR_ENTITY_EMAIL_IS_NOT_COMPLETED |
| 490 | Request blocked by WAF |
**Response Examples:**
**401 (ERR_AUTH_INVALID_CSRF):**
```json
{
"errors": [
{
"code": "ERR_AUTH_INVALID_CSRF",
"message": "Invalid CSRF Authentication"
}
]
}
```
**401 (ERR_AUTH_UNAUTHORIZED):**
```json
{
"errors": [
{
"code": "ERR_AUTH_UNAUTHORIZED",
"message": "Unauthorized"
}
]
}
```
**403 (ERR_ACCESS_USER):**
```json
{
"errors": [
{
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
]
}
```
**403 (ERR_ENTITY_DELETED):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_DELETED",
"message": "Entity is deleted"
}
]
}
```
**403 (ERR_ENTITY_EMAIL_IS_NOT_COMPLETED):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_EMAIL_IS_NOT_COMPLETED",
"message": "Email is not completed"
}
]
}
```
**Code Samples:**
**cURL:**
```shell
curl -X PATCH \
"https://{instance}.kiteworks.com/rest/mail/actions/trash?emailId:in=VALUE" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
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())
```
---
## PATCH /rest/mail/actions/unread
**Summary:** 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.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `emailId:in` | query | yes | Comma-separated list of email IDs to be processed. |
| `partialSuccess` | query | no | If set to `true`, the operation will continue for the valid items even if some items result in failure. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | Email messages marked as unread successfully. |
| 207 | Partially successful — some messages could not be marked as unread. |
| 401 | Unauthorized Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED |
| 403 | Forbidden Possible error codes: ERR_ACCESS_USER, ERR_ENTITY_DELETED |
| 490 | Request blocked by WAF |
**Response Examples:**
**401 (ERR_AUTH_INVALID_CSRF):**
```json
{
"errors": [
{
"code": "ERR_AUTH_INVALID_CSRF",
"message": "Invalid CSRF Authentication"
}
]
}
```
**401 (ERR_AUTH_UNAUTHORIZED):**
```json
{
"errors": [
{
"code": "ERR_AUTH_UNAUTHORIZED",
"message": "Unauthorized"
}
]
}
```
**403 (ERR_ACCESS_USER):**
```json
{
"errors": [
{
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
]
}
```
**403 (ERR_ENTITY_DELETED):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_DELETED",
"message": "Entity is deleted"
}
]
}
```
**Code Samples:**
**cURL:**
```shell
curl -X PATCH \
"https://{instance}.kiteworks.com/rest/mail/actions/unread?emailId:in=VALUE" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
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())
```
---
## GET /rest/mail/{emailId}/attachments/actions/zip
**Summary:** Download email attachments in ZIP format
Using email IDs, downloads a set of email attachments in ZIP format from your Inbox and Sent folders.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `emailId` | path | yes | The unique identifier of the email for downloading attachments as a ZIP file. |
| `attachmentId:in` | query | yes | The unique identifier of the attachment.. Search for results that match any of the specified values for this parameter. |
| `name` | query | no | The name of the ZIP file. |
| `ref` | query | no | The reference ID of the email (Mandatory if the email can be accessed without authentication). |
| `username` | query | no | The email address of the user requesting the file. |
| `utcOffset` | query | no | The user's timezone offset in seconds. For example, UTC+08:00 = 28800 seconds. |
| `mode` | query | no | Determines the detail level of the response body. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | Returns the selected email attachments as a ZIP archive. |
| 403 | Forbidden Possible error codes: ERR_ACCESS_USER |
| 490 | Request blocked by WAF |
**Response Examples:**
**403 (ERR_ACCESS_USER):**
```json
{
"errors": {
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
}
```
**Code Samples:**
**cURL:**
```shell
curl -X GET \
"https://{instance}.kiteworks.com/rest/mail/:emailId/attachments/actions/zip?attachmentId:in=VALUE" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
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 /rest/mail/{emailId}/attachments/actions/zipStatus
**Summary:** 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.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `emailId` | path | yes | The unique identifier of the email. |
| `attachmentId:in` | query | yes | The unique identifier of the attachment.. Search for results that match any of the specified values for this parameter. |
| `ref` | query | no | The reference ID of the email (Mandatory if the email can be accessed without authentication). |
| `mode` | query | no | Determines the detail level of the response body. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | All specified attachments passed security checks and are safe to download. No content is returned. |
| 403 | Forbidden Possible error codes: ERR_ACCESS_USER |
| 490 | Request blocked by WAF |
**Response Examples:**
**403 (ERR_ACCESS_USER):**
```json
{
"errors": {
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
}
```
**Code Samples:**
**cURL:**
```shell
curl -X GET \
"https://{instance}.kiteworks.com/rest/mail/:emailId/attachments/actions/zipStatus?attachmentId:in=VALUE" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
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 /rest/mail/{emailId}/attachments/report
**Summary:** Get email attachment download report
Returns a download tracking report for the specified email, listing all recorded download and interaction events for its attachments.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `emailId` | path | yes | The unique identifier of the email. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | Returns the download tracking report for the specified email. |
| 403 | Forbidden Possible error codes: ERR_ACCESS_USER |
| 490 | Request blocked by WAF |
**Response Examples:**
**200 (AttachmentReport):**
```json
{
"downloads": [
{
"created_time": 1720000000,
"event_name": "download_email",
"username": "recipient@example.com",
"successful": true,
"withdrawn": false,
"file_id": "att12345abc67890de",
"file_name": "Q2_Report.pdf"
}
],
"sent_time": 1719900000,
"subject": "Q2 Reports"
}
```
**403 (ERR_ACCESS_USER):**
```json
{
"errors": {
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
}
```
**Code Samples:**
**cURL:**
```shell
curl -X GET \
"https://{instance}.kiteworks.com/rest/mail/:emailId/attachments/report" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
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())
```
---
## GET /rest/mail/{emailId}/attachments/reportCsv
**Summary:** Export email attachment download report as CSV
Generates a download tracking report for the specified email and returns it as a CSV file.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `emailId` | path | yes | The unique identifier of the email. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | Returns the download tracking report as a CSV file attachment. |
| 403 | Forbidden Possible error codes: ERR_ACCESS_USER |
| 490 | Request blocked by WAF |
**Response Examples:**
**403 (ERR_ACCESS_USER):**
```json
{
"errors": {
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
}
```
**Code Samples:**
**cURL:**
```shell
curl -X GET \
"https://{instance}.kiteworks.com/rest/mail/:emailId/attachments/reportCsv" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
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())
```
---
## GET /rest/mail/{emailId}/attachments/{id}/content
**Summary:** Download email attachment
Downloads the specified file attached to a message.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `emailId` | path | yes | The unique identifier of the email containing the attachment. |
| `id` | path | yes | The unique identifier of the attachment. |
| `Range` | header | no | Range of bytes to download. e.g. `bytes=0-1024` |
| `ref` | query | no | The reference code for the email. Required if the email can be accessed without authentication. |
| `mode` | query | no | Determines the detail level of the response body. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | Returns the binary content of the attachment file. Responds with HTTP 206 Partial Content when a Range header is included in the request. |
| 403 | Forbidden Possible error codes: ERR_ACCESS_USER |
| 490 | Request blocked by WAF |
**Response Examples:**
**403 (ERR_ACCESS_USER):**
```json
{
"errors": {
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
}
```
**Code Samples:**
**cURL:**
```shell
curl -X GET \
"https://{instance}.kiteworks.com/rest/mail/:emailId/attachments/:id/content" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
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 /rest/mail/{emailId}/attachments/{id}/preview
**Summary:** 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.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `emailId` | path | yes | The unique identifier of the email containing the attachment. |
| `id` | path | yes | The unique identifier of the attachment. |
| `ref` | query | no | The reference code for the email. Required if the email can be accessed without authentication. |
| `mode` | query | no | Determines the detail level of the response body. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | Returns the preview metadata for the specified attachment, including the URL to render the preview. |
| 403 | Forbidden Possible error codes: ERR_ACCESS_USER |
| 490 | Request blocked by WAF |
**Response Examples:**
**200 (AttachmentPreview):**
```json
{
"link": "/preview/abc12345def67890ab",
"viewUrl": "https:///viewer/abc12345def67890ab",
"status": "Preview",
"watermark": null
}
```
**403 (ERR_ACCESS_USER):**
```json
{
"errors": {
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
}
```
**Code Samples:**
**cURL:**
```shell
curl -X GET \
"https://{instance}.kiteworks.com/rest/mail/:emailId/attachments/:id/preview" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
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 /rest/mail/{id}
**Summary:** 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.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier (UUID) of the email. |
| `returnEntity` | query | no | If true, includes the entity in the response body. |
| `with` | query | no | Specifies additional fields to include in the response. |
| `mode` | query | no | Determines the detail level of the response body. |
| `ref` | query | no | The reference ID of the email (Mandatory if the email can be accessed without authentication). |
| `print_flag` | query | no | Indicates whether the user clicked to print the email. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | Email metadata returned successfully. |
| 490 | Request blocked by WAF |
**Code Samples:**
**cURL:**
```shell
curl -X GET \
"https://{instance}.kiteworks.com/rest/mail/:id" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
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 /rest/mail/{id}
**Summary:** 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.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier (UUID) of the email. |
**Responses:**
| Code | Description |
|------|-------------|
| 204 | Draft email deleted successfully. |
| 401 | Unauthorized Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED |
| 403 | Forbidden Possible error codes: ERR_ACCESS_NOT_SENDER, ERR_ACCESS_USER, ERR_ENTITY_EMAIL_IS_SENT, ERR_PROFILE_MAIL_DISABLED, ERR_ENTITY_DELETED |
| 490 | Request blocked by WAF |
**Response Examples:**
**401 (ERR_AUTH_INVALID_CSRF):**
```json
{
"errors": [
{
"code": "ERR_AUTH_INVALID_CSRF",
"message": "Invalid CSRF Authentication"
}
]
}
```
**401 (ERR_AUTH_UNAUTHORIZED):**
```json
{
"errors": [
{
"code": "ERR_AUTH_UNAUTHORIZED",
"message": "Unauthorized"
}
]
}
```
**403 (ERR_ACCESS_NOT_SENDER):**
```json
{
"errors": [
{
"code": "ERR_ACCESS_NOT_SENDER",
"message": "Authenticated user is not the sender of the specified email"
}
]
}
```
**403 (ERR_ACCESS_USER):**
```json
{
"errors": [
{
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
]
}
```
**403 (ERR_ENTITY_EMAIL_IS_SENT):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_EMAIL_IS_SENT",
"message": "Email can no longer be deleted"
}
]
}
```
**403 (ERR_PROFILE_MAIL_DISABLED):**
```json
{
"errors": [
{
"code": "ERR_PROFILE_MAIL_DISABLED",
"message": "User's profile has no mail access"
}
]
}
```
**403 (ERR_ENTITY_DELETED):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_DELETED",
"message": "Entity is deleted"
}
]
}
```
**Code Samples:**
**cURL:**
```shell
curl -X DELETE \
"https://{instance}.kiteworks.com/rest/mail/:id" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
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())
```
---
## PUT /rest/mail/{id}/actions/sendFile
**Summary:** 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.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier (UUID) of the email. |
| `returnEntity` | query | no | If true, includes the entity in the response body. |
| `with` | query | no | Specifies additional fields to include in the response. |
| `mode` | query | no | Determines the detail level of the response body. |
**Request Body:**
| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `to` | string[] | no | List of recipients' email addresses (To field). |
| `cc` | string[] | no | List of recipients' email addresses (CC field). |
| `bcc` | string[] | no | List of recipients' email addresses (BCC field). |
| `files` | string[] | no | List of file UUIDs to attach to the email. |
| `acl` | string | no | 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. |
| `expire` | string | no | The expiration date of the email. |
| `draft` | boolean | no | Indicates if the email is being saved as a draft. |
| `preview` | boolean | no | Indicates if the email is a view-only version. |
| `watermark` | string | no | Text watermark applied to the email attachments (only applicable when `preview` is enabled). |
| `secureBody` | boolean | no | If true, the email body is hidden from the notification email and is only visible to authenticated recipients when they open the secure link. |
| `selfCopy` | boolean | no | Indicates if the sender should receive a copy of the email. |
| `includeFingerprint` | boolean | no | If true, a cryptographic hash (fingerprint) of each attached file is included in the notification email, allowing recipients to verify file integrity. |
| `parentEmailId` | string | no | The parent email ID used for email threading. Applicable only for `forward` or `reply` types. |
| `isSelfReturnReceipt` | boolean | no | (Deprecated) Send download notification to the sender. Use 'returnReceipts' instead. |
| `returnReceipts` | string[] | no | List of recipients who should receive a download notification. |
| `type` | string | no | 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. |
| `uploading` | boolean | no | Indicates whether file upload is still in progress. Prevents sending if set to `true`. |
| `body` | string | no | The body content of the email. |
| `subject` | string | no | The subject of the email (maximum length: 998 characters). |
| `webFormId` | string | no | The web form ID associated with the email. |
| `webFormFields` | object | no | Custom web form fields associated with the email. |
| `notifyExpired` | boolean | no | Indicates whether to send a notification email to the sender when the email expires. |
| `sharedMailboxId` | string | no | 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. |
| `trackingAccess` | string[] | no | List of email addresses to grant access to the email's download tracking dashboard. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | Draft email updated and sent successfully. |
| 401 | Unauthorized Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED |
| 403 | 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 |
| 422 | 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) |
| 490 | Request blocked by WAF |
**Response Examples:**
**401 (ERR_AUTH_INVALID_CSRF):**
```json
{
"errors": [
{
"code": "ERR_AUTH_INVALID_CSRF",
"message": "Invalid CSRF Authentication"
}
]
}
```
**401 (ERR_AUTH_UNAUTHORIZED):**
```json
{
"errors": [
{
"code": "ERR_AUTH_UNAUTHORIZED",
"message": "Unauthorized"
}
]
}
```
**403 (ERR_ACCESS_NOT_SENDER):**
```json
{
"errors": [
{
"code": "ERR_ACCESS_NOT_SENDER",
"message": "Authenticated user is not the sender of the specified email"
}
]
}
```
**403 (ERR_ACCESS_USER):**
```json
{
"errors": [
{
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
]
}
```
**403 (ERR_ENTITY_DELETED):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_DELETED",
"message": "Entity is deleted"
}
]
}
```
**403 (ERR_ENTITY_EMAIL_NOT_DRAFT):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_EMAIL_NOT_DRAFT",
"message": "The specified email can no longer be updated."
}
]
}
```
**403 (ERR_ENTITY_IS_DELETED_ATTACHMENT):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_IS_DELETED_ATTACHMENT",
"message": "Requested Attachment(s) is deleted"
}
]
}
```
**403 (ERR_ENTITY_IS_SECURE_FOLDER):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_IS_SECURE_FOLDER",
"message": "Operation not permitted on restricted Folder."
}
]
}
```
**403 (ERR_INPUT_EMAIL_WITH_NO_RECIPIENTS_NOT_ALLOWED):**
```json
{
"errors": [
{
"code": "ERR_INPUT_EMAIL_WITH_NO_RECIPIENTS_NOT_ALLOWED",
"message": "The mail cannot be sent without any recipients"
}
]
}
```
**403 (ERR_INPUT_SECURE_BODY_WITH_NO_AUTH_NOT_ALLOWED):**
```json
{
"errors": [
{
"code": "ERR_INPUT_SECURE_BODY_WITH_NO_AUTH_NOT_ALLOWED",
"message": "Email message body cannot be secured if email does not require authentication"
}
]
}
```
**403 (ERR_PROFILE_INCLUDE_FINGERPRINT_DISABLED):**
```json
{
"errors": [
{
"code": "ERR_PROFILE_INCLUDE_FINGERPRINT_DISABLED",
"message": "This profile is not allowed to include fingerprint with sent files"
}
]
}
```
**403 (ERR_PROFILE_INCLUDE_FINGERPRINT_ENABLED):**
```json
{
"errors": [
{
"code": "ERR_PROFILE_INCLUDE_FINGERPRINT_ENABLED",
"message": "This profile cannot disable including fingerprint with sent files"
}
]
}
```
**403 (ERR_PROFILE_RETURN_RECEIPT_DISABLED):**
```json
{
"errors": [
{
"code": "ERR_PROFILE_RETURN_RECEIPT_DISABLED",
"message": "This profile is not allowed to set receipt notification with sent files"
}
]
}
```
**403 (ERR_PROFILE_RETURN_RECEIPT_ENABLED):**
```json
{
"errors": [
{
"code": "ERR_PROFILE_RETURN_RECEIPT_ENABLED",
"message": "This profile cannot disable return receipt notification with sent files"
}
]
}
```
**403 (ERR_PROFILE_SECURE_EMAIL_DISABLED):**
```json
{
"errors": [
{
"code": "ERR_PROFILE_SECURE_EMAIL_DISABLED",
"message": "This profile is not allowed to send secure emails"
}
]
}
```
**403 (ERR_PROFILE_SELF_COPY_DISABLED):**
```json
{
"errors": [
{
"code": "ERR_PROFILE_SELF_COPY_DISABLED",
"message": "This profile is not allowed to send copy to self"
}
]
}
```
**403 (ERR_PROFILE_SELF_COPY_ENABLED):**
```json
{
"errors": [
{
"code": "ERR_PROFILE_SELF_COPY_ENABLED",
"message": "Cannot disable self copy for this profile"
}
]
}
```
**403 (ERR_PROFILE_SEND_FILE_EXTERNAL_DISABLED):**
```json
{
"errors": [
{
"code": "ERR_PROFILE_SEND_FILE_EXTERNAL_DISABLED",
"message": "This profile is not allowed to send files to external users"
}
]
}
```
**403 (ERR_USER_HAS_NO_USER_TYPE):**
```json
{
"errors": [
{
"code": "ERR_USER_HAS_NO_USER_TYPE",
"message": "User has no profile"
}
]
}
```
**403 (ERR_USER_TYPE_NO_ACCESS):**
```json
{
"errors": [
{
"code": "ERR_USER_TYPE_NO_ACCESS",
"message": "Permission denied"
}
]
}
```
**422 (ERR_INPUT_EXCEEDS_MAX_VALUE):**
```json
{
"errors": [
{
"code": "ERR_INPUT_EXCEEDS_MAX_VALUE",
"message": "Field value exceeds maximum allowed value"
}
]
}
```
**422 (ERR_INPUT_HYPERLINK):**
```json
{
"errors": [
{
"code": "ERR_INPUT_HYPERLINK",
"message": "Not allowed hyperlink domain. Hyperlink domain should not different from anchored text domain."
}
]
}
```
**422 (ERR_INPUT_INVALID_DATE):**
```json
{
"errors": [
{
"code": "ERR_INPUT_INVALID_DATE",
"message": "The input is not a valid date."
}
]
}
```
**422 (ERR_INPUT_PAST_DATE):**
```json
{
"errors": [
{
"code": "ERR_INPUT_PAST_DATE",
"message": "Field value should be future date"
}
]
}
```
**422 (ERR_INVALID_PARAMETER):**
```json
{
"errors": [
{
"code": "ERR_INVALID_PARAMETER",
"message": "Invalid Parameter Exception"
}
]
}
```
**Code Samples:**
**cURL:**
```shell
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"
}'
```
**Python:**
```python
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 /rest/mail/{id}/attachments
**Summary:** 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.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier (UUID) of the email. |
| `limit` | query | no | Maximum number of attachments to return. |
| `offset` | query | no | Number of attachments to skip before returning results, for pagination. |
| `ref` | query | no | The reference ID of the email (Mandatory if the email can be accessed without authentication). |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | Email attachments returned successfully. |
| 401 | Unauthorized Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED |
| 403 | Forbidden Possible error codes: ERR_ACCESS_USER |
| 490 | Request blocked by WAF |
**Response Examples:**
**401 (ERR_AUTH_INVALID_CSRF):**
```json
{
"errors": [
{
"code": "ERR_AUTH_INVALID_CSRF",
"message": "Invalid CSRF Authentication"
}
]
}
```
**401 (ERR_AUTH_UNAUTHORIZED):**
```json
{
"errors": [
{
"code": "ERR_AUTH_UNAUTHORIZED",
"message": "Unauthorized"
}
]
}
```
**403 (ERR_ACCESS_USER):**
```json
{
"errors": [
{
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
]
}
```
**Code Samples:**
**cURL:**
```shell
curl -X GET \
"https://{instance}.kiteworks.com/rest/mail/:id/attachments" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
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 /rest/mail/{id}/attachments/{attachment_id}
**Summary:** 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.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier (UUID) of the email. |
| `attachment_id` | path | yes | The unique identifier (UUID) of the attachment. |
| `ref` | query | no | The reference ID of the email (Mandatory if the email can be accessed without authentication). |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | Email attachment returned successfully. |
| 401 | Unauthorized Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED |
| 403 | Forbidden Possible error codes: ERR_ACCESS_USER |
| 490 | Request blocked by WAF |
**Response Examples:**
**401 (ERR_AUTH_INVALID_CSRF):**
```json
{
"errors": [
{
"code": "ERR_AUTH_INVALID_CSRF",
"message": "Invalid CSRF Authentication"
}
]
}
```
**401 (ERR_AUTH_UNAUTHORIZED):**
```json
{
"errors": [
{
"code": "ERR_AUTH_UNAUTHORIZED",
"message": "Unauthorized"
}
]
}
```
**403 (ERR_ACCESS_USER):**
```json
{
"errors": [
{
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
]
}
```
**Code Samples:**
**cURL:**
```shell
curl -X GET \
"https://{instance}.kiteworks.com/rest/mail/:id/attachments/:attachment_id" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
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 /rest/mail/{id}/packages
**Summary:** 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.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier (UUID) of the email. |
| `ref` | query | no | The reference ID of the email (Mandatory if the email can be accessed without authentication). |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | Email package returned successfully. |
| 401 | Unauthorized Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED |
| 403 | Forbidden Possible error codes: ERR_ACCESS_USER |
| 490 | Request blocked by WAF |
**Response Examples:**
**401 (ERR_AUTH_INVALID_CSRF):**
```json
{
"errors": [
{
"code": "ERR_AUTH_INVALID_CSRF",
"message": "Invalid CSRF Authentication"
}
]
}
```
**401 (ERR_AUTH_UNAUTHORIZED):**
```json
{
"errors": [
{
"code": "ERR_AUTH_UNAUTHORIZED",
"message": "Unauthorized"
}
]
}
```
**403 (ERR_ACCESS_USER):**
```json
{
"errors": [
{
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
]
}
```
**Code Samples:**
**cURL:**
```shell
curl -X GET \
"https://{instance}.kiteworks.com/rest/mail/:id/packages" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
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 /rest/mail/{id}/recipients
**Summary:** 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.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier (UUID) of the email. |
| `returnEntity` | query | no | If true, includes the entity in the response body. |
| `with` | query | no | Specifies additional fields to include in the response. |
| `mode` | query | no | Determines the detail level of the response body. |
| `ref` | query | no | The reference ID of the email (Mandatory if the email can be accessed without authentication). |
| `orderBy` | query | no | Sort order for the recipient list. Default is `type:asc`. Allowed values: `id:asc`, `id:desc`, `type:asc`, `type:desc`. |
| `type` | query | no | Filter recipients by type. Accepts a comma-separated list of integer values. `0` – To. `1` – CC. `2` – BCC. |
| `limit` | query | no | Range limit. |
| `offset` | query | no | Range offset. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | Email recipients returned successfully. |
| 401 | Unauthorized Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED |
| 403 | Forbidden Possible error codes: ERR_ACCESS_USER |
| 490 | Request blocked by WAF |
**Response Examples:**
**401 (ERR_AUTH_INVALID_CSRF):**
```json
{
"errors": [
{
"code": "ERR_AUTH_INVALID_CSRF",
"message": "Invalid CSRF Authentication"
}
]
}
```
**401 (ERR_AUTH_UNAUTHORIZED):**
```json
{
"errors": [
{
"code": "ERR_AUTH_UNAUTHORIZED",
"message": "Unauthorized"
}
]
}
```
**403 (ERR_ACCESS_USER):**
```json
{
"errors": [
{
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
]
}
```
**Code Samples:**
**cURL:**
```shell
curl -X GET \
"https://{instance}.kiteworks.com/rest/mail/:id/recipients" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
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())
```
---
## POST /rest/mail/{id}/actions/withdrawFiles
**Summary:** 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.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier (UUID) of the email. |
| `id:in` | query | yes | A comma-separated list of attachment IDs to be withdrawn. |
| `sharedMailboxId` | query | no | The unique identifier of the Shared Mailbox. If provided, the operation will be performed within the specified Shared Mailbox context. |
**Responses:**
| Code | Description |
|------|-------------|
| 204 | Attachments withdrawn successfully. |
| 401 | Unauthorized Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED |
| 403 | Forbidden Possible error codes: ERR_ACCESS_NOT_SENDER, ERR_ACCESS_USER, ERR_ENTITY_DELETED, ERR_ENTITY_IS_DELETED_ATTACHMENT |
| 422 | Unprocessable Content Possible error codes: ERR_INVALID_PARAMETER |
| 490 | Request blocked by WAF |
**Response Examples:**
**401 (ERR_AUTH_INVALID_CSRF):**
```json
{
"errors": [
{
"code": "ERR_AUTH_INVALID_CSRF",
"message": "Invalid CSRF Authentication"
}
]
}
```
**401 (ERR_AUTH_UNAUTHORIZED):**
```json
{
"errors": [
{
"code": "ERR_AUTH_UNAUTHORIZED",
"message": "Unauthorized"
}
]
}
```
**403 (ERR_ACCESS_NOT_SENDER):**
```json
{
"errors": [
{
"code": "ERR_ACCESS_NOT_SENDER",
"message": "Authenticated user is not the sender of the specified email"
}
]
}
```
**403 (ERR_ACCESS_USER):**
```json
{
"errors": [
{
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
]
}
```
**403 (ERR_ENTITY_DELETED):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_DELETED",
"message": "Entity is deleted"
}
]
}
```
**403 (ERR_ENTITY_IS_DELETED_ATTACHMENT):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_IS_DELETED_ATTACHMENT",
"message": "Requested Attachment(s) is deleted"
}
]
}
```
**422 (ERR_INVALID_PARAMETER):**
```json
{
"errors": [
{
"code": "ERR_INVALID_PARAMETER",
"message": "Invalid Parameter Exception"
}
]
}
```
**Code Samples:**
**cURL:**
```shell
curl -X POST \
"https://{instance}.kiteworks.com/rest/mail/:id/actions/withdrawFiles?id:in=VALUE" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
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())
```
---
## POST /rest/mail/{id}/actions/copy
**Summary:** 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.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier (UUID) of the email. |
| `id:in` | query | yes | |
| `returnEntity` | query | no | If true, includes the entity in the response body. |
| `with` | query | no | Specifies additional fields to include in the response. |
| `mode` | query | no | Determines the detail level of the response body. |
**Request Body:**
| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `destinationFolderId` | string | yes | The ID of the destination folder where the item will be copied/moved. |
| `addVersion` | boolean | no | If a file with the same name exists, create a new version instead of overwriting it. Default is True. |
**Responses:**
| Code | Description |
|------|-------------|
| 201 | Attachment files copied successfully. |
| 401 | Unauthorized Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED |
| 403 | 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 |
| 422 | Unprocessable Content Possible error codes: ERR_INVALID_PARAMETER |
| 490 | Request blocked by WAF |
**Response Examples:**
**401 (ERR_AUTH_INVALID_CSRF):**
```json
{
"errors": [
{
"code": "ERR_AUTH_INVALID_CSRF",
"message": "Invalid CSRF Authentication"
}
]
}
```
**401 (ERR_AUTH_UNAUTHORIZED):**
```json
{
"errors": [
{
"code": "ERR_AUTH_UNAUTHORIZED",
"message": "Unauthorized"
}
]
}
```
**403 (ERR_ACCESS_NOT_SENDER):**
```json
{
"errors": [
{
"code": "ERR_ACCESS_NOT_SENDER",
"message": "Authenticated user is not the sender of the specified email"
}
]
}
```
**403 (ERR_ACCESS_USER):**
```json
{
"errors": [
{
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
]
}
```
**403 (ERR_ENTITY_DELETED):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_DELETED",
"message": "Entity is deleted"
}
]
}
```
**403 (ERR_ENTITY_IS_BASE_DIR):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_IS_BASE_DIR",
"message": "Operation not permitted on Base Folder"
}
]
}
```
**403 (ERR_ENTITY_IS_DELETED_ATTACHMENT):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_IS_DELETED_ATTACHMENT",
"message": "Requested Attachment(s) is deleted"
}
]
}
```
**403 (ERR_ENTITY_IS_MY_DIR):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_IS_MY_DIR",
"message": "Operation not permitted on Tray Folder"
}
]
}
```
**403 (ERR_ENTITY_IS_SECURE_FOLDER):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_IS_SECURE_FOLDER",
"message": "Operation not permitted on restricted Folder."
}
]
}
```
**403 (ERR_ENTITY_RESTRICTED_EXTENSION):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_RESTRICTED_EXTENSION",
"message": "File extension is in exclusion extensions list"
}
]
}
```
**403 (ERR_ENTITY_RESTRICTED_TYPE):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_RESTRICTED_TYPE",
"message": "The specified entity mime type is not allowed."
}
]
}
```
**422 (ERR_INVALID_PARAMETER):**
```json
{
"errors": [
{
"code": "ERR_INVALID_PARAMETER",
"message": "Invalid Parameter Exception"
}
]
}
```
**Code Samples:**
**cURL:**
```shell
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
}'
```
**Python:**
```python
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())
```
---
## POST /rest/mail/{id}/actions/sendTrackingReport
**Summary:** 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.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier (UUID) of the email. |
| `returnEntity` | query | no | If true, includes the entity in the response body. |
| `with` | query | no | Specifies additional fields to include in the response. |
| `mode` | query | no | Determines the detail level of the response body. |
**Responses:**
| Code | Description |
|------|-------------|
| 201 | Tracking report sent successfully. |
| 401 | Unauthorized Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED |
| 403 | Forbidden Possible error codes: ERR_ACCESS_NOT_SENDER, ERR_ACCESS_USER |
| 490 | Request blocked by WAF |
**Response Examples:**
**401 (ERR_AUTH_INVALID_CSRF):**
```json
{
"errors": [
{
"code": "ERR_AUTH_INVALID_CSRF",
"message": "Invalid CSRF Authentication"
}
]
}
```
**401 (ERR_AUTH_UNAUTHORIZED):**
```json
{
"errors": [
{
"code": "ERR_AUTH_UNAUTHORIZED",
"message": "Unauthorized"
}
]
}
```
**403 (ERR_ACCESS_NOT_SENDER):**
```json
{
"errors": [
{
"code": "ERR_ACCESS_NOT_SENDER",
"message": "Authenticated user is not the sender of the specified email"
}
]
}
```
**403 (ERR_ACCESS_USER):**
```json
{
"errors": [
{
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
]
}
```
**Code Samples:**
**cURL:**
```shell
curl -X POST \
"https://{instance}.kiteworks.com/rest/mail/:id/actions/sendTrackingReport" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
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 /rest/mail/attachments
**Summary:** 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 |
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `limit` | query | no | Range limit. |
| `offset` | query | no | Range offset. |
| `bucket` | query | no | 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. |
| `orderBy` | query | no | 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`. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | Email attachments returned successfully. |
| 401 | Unauthorized Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED |
| 490 | Request blocked by WAF |
**Response Examples:**
**401 (ERR_AUTH_INVALID_CSRF):**
```json
{
"errors": [
{
"code": "ERR_AUTH_INVALID_CSRF",
"message": "Invalid CSRF Authentication"
}
]
}
```
**401 (ERR_AUTH_UNAUTHORIZED):**
```json
{
"errors": [
{
"code": "ERR_AUTH_UNAUTHORIZED",
"message": "Unauthorized"
}
]
}
```
**Code Samples:**
**cURL:**
```shell
curl -X GET \
"https://{instance}.kiteworks.com/rest/mail/attachments" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
import requests
url = "https://{instance}.kiteworks.com/rest/mail/attachments"
headers = {
"Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
```
---
## DELETE /rest/mail/attachments
**Summary:** 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.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id:in` | query | yes | |
**Responses:**
| Code | Description |
|------|-------------|
| 204 | Specified attachments withdrawn successfully. |
| 401 | Unauthorized Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED |
| 422 | Unprocessable Content Possible error codes: ERR_INVALID_PARAMETER |
| 490 | Request blocked by WAF |
**Response Examples:**
**401 (ERR_AUTH_INVALID_CSRF):**
```json
{
"errors": [
{
"code": "ERR_AUTH_INVALID_CSRF",
"message": "Invalid CSRF Authentication"
}
]
}
```
**401 (ERR_AUTH_UNAUTHORIZED):**
```json
{
"errors": [
{
"code": "ERR_AUTH_UNAUTHORIZED",
"message": "Unauthorized"
}
]
}
```
**422 (ERR_INVALID_PARAMETER):**
```json
{
"errors": [
{
"code": "ERR_INVALID_PARAMETER",
"message": "Invalid Parameter Exception"
}
]
}
```
**Code Samples:**
**cURL:**
```shell
curl -X DELETE \
"https://{instance}.kiteworks.com/rest/mail/attachments?id:in=VALUE" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
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())
```
---
## POST /rest/mail/actions/withdraw
**Summary:** 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.
**Request Body:**
| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `ids` | string[] | yes | List of email UUIDs to withdraw. Withdrawing an email revokes recipient access to its attachments. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | Email messages withdrawn successfully. |
| 207 | Partially successful — some messages could not be withdrawn. |
| 401 | Unauthorized Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED |
| 403 | 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 |
| 490 | Request blocked by WAF |
**Response Examples:**
**401 (ERR_AUTH_INVALID_CSRF):**
```json
{
"errors": [
{
"code": "ERR_AUTH_INVALID_CSRF",
"message": "Invalid CSRF Authentication"
}
]
}
```
**401 (ERR_AUTH_UNAUTHORIZED):**
```json
{
"errors": [
{
"code": "ERR_AUTH_UNAUTHORIZED",
"message": "Unauthorized"
}
]
}
```
**403 (ERR_ACCESS_USER):**
```json
{
"errors": [
{
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
]
}
```
**403 (ERR_ENTITY_DELETED):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_DELETED",
"message": "Entity is deleted"
}
]
}
```
**403 (ERR_ENTITY_EMAIL_IS_NOT_COMPLETED):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_EMAIL_IS_NOT_COMPLETED",
"message": "Email is not completed"
}
]
}
```
**403 (ERR_ACCESS_NOT_SENDER):**
```json
{
"errors": [
{
"code": "ERR_ACCESS_NOT_SENDER",
"message": "Authenticated user is not the sender of the specified email"
}
]
}
```
**403 (ERR_MAIL_BODY_UNSECURED):**
```json
{
"errors": [
{
"code": "ERR_MAIL_BODY_UNSECURED",
"message": "Mail body is unsecured."
}
]
}
```
**403 (ERR_ENTITY_IS_EMAIL_CONTENT):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_IS_EMAIL_CONTENT",
"message": "Operation not permitted on email content"
}
]
}
```
**Code Samples:**
**cURL:**
```shell
curl -X POST \
"https://{instance}.kiteworks.com/rest/mail/actions/withdraw" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"ids": [
"string"
]
}'
```
**Python:**
```python
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 /rest/mail/{id}/scanStatus
**Summary:** 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.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier (UUID) of the email. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | Message and attachments (if any) have passed all security scans successfully. |
| 401 | Unauthorized Possible error codes: ERR_AUTH_UNAUTHORIZED |
| 403 | Forbidden Possible error codes: ERR_ACCESS_USER, ERR_ENTITY_EMAIL_IS_DRAFT, ERR_ENTITY_EMAIL_SCANNING, ERR_ENTITY_EMAIL_SCANNING_DISALLOWED |
| 490 | Request blocked by WAF |
**Response Examples:**
**401 (ERR_AUTH_UNAUTHORIZED):**
```json
{
"errors": [
{
"code": "ERR_AUTH_UNAUTHORIZED",
"message": "Unauthorized"
}
]
}
```
**403 (ERR_ACCESS_USER):**
```json
{
"errors": [
{
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
]
}
```
**403 (ERR_ENTITY_EMAIL_IS_DRAFT):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_EMAIL_IS_DRAFT",
"message": "The action cannot be performed on draft."
}
]
}
```
**403 (ERR_ENTITY_EMAIL_SCANNING):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_EMAIL_SCANNING",
"message": "One or more files, or the email, are undergoing security and privacy scans. Please try again later."
}
]
}
```
**403 (ERR_ENTITY_EMAIL_SCANNING_DISALLOWED):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_EMAIL_SCANNING_DISALLOWED",
"message": "One or more files, or the email, are blocked by system policy."
}
]
}
```
**Code Samples:**
**cURL:**
```shell
curl -X GET \
"https://{instance}.kiteworks.com/rest/mail/:id/scanStatus" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
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())
```
---
## DELETE /rest/mail/{id}/trackings/me
**Summary:** 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.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier (UUID) of the email. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | Email tracking access removed successfully. |
| 401 | Unauthorized Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED |
| 403 | Forbidden Possible error codes: ERR_ACCESS_USER, ERR_ENTITY_DELETED |
| 490 | Request blocked by WAF |
**Response Examples:**
**401 (ERR_AUTH_INVALID_CSRF):**
```json
{
"errors": [
{
"code": "ERR_AUTH_INVALID_CSRF",
"message": "Invalid CSRF Authentication"
}
]
}
```
**401 (ERR_AUTH_UNAUTHORIZED):**
```json
{
"errors": [
{
"code": "ERR_AUTH_UNAUTHORIZED",
"message": "Unauthorized"
}
]
}
```
**403 (ERR_ACCESS_USER):**
```json
{
"errors": [
{
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
]
}
```
**403 (ERR_ENTITY_DELETED):**
```json
{
"errors": [
{
"code": "ERR_ENTITY_DELETED",
"message": "Entity is deleted"
}
]
}
```
**Code Samples:**
**cURL:**
```shell
curl -X DELETE \
"https://{instance}.kiteworks.com/rest/mail/:id/trackings/me" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**Python:**
```python
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())
```
---
## PUT /rest/mail/{id}/settings
**Summary:** 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.
**Parameters:**
| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier (UUID) of the email. |
**Request Body:**
| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `trackingAccess` | string[] | no | List of email addresses to grant access to the email's download tracking dashboard. |
**Responses:**
| Code | Description |
|------|-------------|
| 200 | Mail tracking settings updated successfully. |
| 401 | Unauthorized Possible error codes: ERR_AUTH_UNAUTHORIZED |
| 403 | Forbidden Possible error codes: ERR_ACCESS_USER, ERR_NOT_INTERNAL_DOMAIN, ERR_INSUFFICIENT_TRACKING_PERMISSIONS |
| 490 | Request blocked by WAF |
**Response Examples:**
**401 (ERR_AUTH_UNAUTHORIZED):**
```json
{
"errors": [
{
"code": "ERR_AUTH_UNAUTHORIZED",
"message": "Unauthorized"
}
]
}
```
**403 (ERR_ACCESS_USER):**
```json
{
"errors": [
{
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
]
}
```
**403 (ERR_NOT_INTERNAL_DOMAIN):**
```json
{
"errors": [
{
"code": "ERR_NOT_INTERNAL_DOMAIN",
"message": "The email is not internal domain"
}
]
}
```
**403 (ERR_INSUFFICIENT_TRACKING_PERMISSIONS):**
```json
{
"errors": [
{
"code": "ERR_INSUFFICIENT_TRACKING_PERMISSIONS",
"message": "This profile is not allowed to give tracking access due to insufficient permissions"
}
]
}
```
**Code Samples:**
**cURL:**
```shell
curl -X PUT \
"https://{instance}.kiteworks.com/rest/mail/:id/settings" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"trackingAccess": [
"string"
]
}'
```
**Python:**
```python
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())
```
---