Manage mail

This section provides steps on how to:

  • Create an email

  • Attach a file to the email draft

  • Send the email

Create email

HTTP Method

Request URL
POST

https://{base_url}/rest/mail/actions/sendFile

Request Body

Define the parameters of your email in the request body - subject, email body, recipients, etc.

If the value of the draft parameter is set to true, the email is saved as a draft. If set to false, the email is sent immediately.

Copy
Example Request Body
{
    "subject": "Test mail subject",
    "body": "Test mail body",
    "to": [
        "recipient1@example.com",
        "recipient2@example.com"
    ],
    "cc": [],
    "bcc": [],
    "draft": "true",
    "secureBody": "false"
}

A successful request returns a 201 Created status code. If the query parameter returnEntity was set to true during the request, the newly created email object is returned in the response body.

The value of the id parameter in the response provides the UUID of the email. This is used to retrieve the object, as well as attach a file to it and send it, if it is a draft.

Example request

Copy

Example Request

curl -X POST "{base_url}/rest/mail/actions/sendFile?returnEntity=True" \
  -H "X-Accellion-Version: 28" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "subject": "Test mail subject",
        "body": "Test mail body",
        "to": [
            "recipient1@example.com",
            "recipient2@example.com"
        ],
        "cc": [],
        "bcc": [],
        "draft": "true",
        "secureBody": "false"
    }'
Copy

Example response

{
    "hasTrackingAccess": true,
    "policyDirective": 0,
    "dlpStatus": null,
    "status": "draft",
    "date": "2026-02-04T14:15:04+0000",
    "modifiedDate": "2026-02-04T14:15:04+0000",
    "withdrawnDate": null,
    "type": "original",
    "senderId": "a111b222-c333-d444-e555-f666777888aaa",
    "emailReturnReceipt": [
        {
            "user": {
                    "profileIcon": "a111b222-c333-d444-e555-f666777888aaa",
                    "name": "John Doe",
                    "id": "a111b222-c333-d444-e555-f666777888aaa",
                    "email": "user@example.com"
            }
        }
    ],
    "emailPackageId": "a1b2c3d4-e5f6-1a2b-3c4d-5e6f7a8b9c0d",
    "avStatus": null,
    "isUserSent": true,
    "error": null,
    "bucket": "draft",
    "attachmentCount": 0,
    "webFormId": null,
    "rawBody": "Test email body",
    "secureBody": true,
    "id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
    "trackingAccess": [],
    "emailFrom": "user@example.com",
    "isRead": false,
    "isPreview": false,
    "watermark": null,
    "expirationDate": "2026-03-06T23:59:59+0000",
    "recipients": [
        {
            "type": 0,
            "email": "recipient1@example.com",
            "userId": "f9e8d7c6-b5a4-3f2e-1d0c-9b8a7f6e5d4c",
            "isDistributionList": false
        },
                {
            "type": 0,
            "email": "recipient2@example.com",
            "userId": "e8d7c6b5-a4f3-2e1d-0c9b-8a7f6e5d4c3b",
            "isDistributionList": false
        }
    ],
    "deleted": false,
    "templateId": 73,
    "body": "<p style=\"margin: 0px;\">Test email body</p>",
    "sharedMailboxId": null,
    "subject": "Test email subject",
    "parentEmailId": null
}

Attach files to email

This example demonstrates how to attach a file to an email draft. You must initiate a multi-chunks Upload before you can upload any part. In the response of your initiate request, the API returns an upload ID that you must include in the upload as part of the request. In this example, a file 'MyNewFile.txt' will be attached in 2 chunks with 1KB in each chunk (the user can choose their own chunk size).

HTTP Method

Request URL
POST

https://{base_url}/rest/mail/{mail_id}/actions/initiateUpload

Request Body

filename - The new file name

totalSize - the total size of the file

totalChunks - the total number of chunks

Copy
Example request body
{
  "filename": "MyNewFile.txt",
  "totalSize": 2048,
  "totalChunks": 2
}

Response

If the upload is initiated successfully, the response is a 201 Created status code. The response body contains a JSON representation of the chunk upload info, including a uri parameter (dacfs_upload1/rest/uploads/7890 in this sample request) that you can use as the value of upload_id for subsequent requests.

Example request and response

Copy

Example request

   -X POST 'https://{hostname}/rest/folders/1234/actions/initiateUpload' \
   -H 'Accept: application/json' \
   -H 'Content-Type: application/json' \
   -H 'X-Kiteworks-Version: 15' \
   -H 'Authorization: Bearer {access_token}' \
   -d '{"filename": "MyNewFile.txt", "totalSize": 2048, totalChunks': 2}'
Copy

Example response

{
    "error": "OK",
    "totalSize": 2048,
    "timestamp": "2020-05-15T08:11:07Z",
    "uri": "dacfs_upload1/rest/uploads/7890",
    "userId": 1,
    "lastTimestamp": "2020-05-15T08:11:07Z",
    "uploadedSize": 0,
    "clientName": "API Playground",
    "fileUrl": "",
    "location": "{hostname}",
    "totalChunks": 2,
    "uploadedChunks": 0,
    "completeOk": 0,
    "svrUploadTime": 0,
    "id": 7890,
    "replaceId": null,
    "backend": "acfs"
}

Chunk upload

HTTP Method

Request URL
POST

https://{base_url}/{upload_url}

Request Body

HTTP Method

Request URL
compressMode

The compression mode of the chunk (only NORMAL is supported).

compressionSize

The compressed size (it’s always the same as originalSize).

originalSize

The original size of the chunk.

index

The chunk index for this file. Starts from 1.

lastChunk

When set to '1', indicates that this is the last chunk, after which the upload is completed.
Copy
Example request body
{
  "compressionMode": "NORMAL",
  "compressionSize": 1024,
  "originalSize": 1024,
  "index": 1
}

Response

If the individual chunk is completed, the response is a 200 OK status code. Once the whole multi-chunks upload is completed successfully, the response is a 201 Created status code. The response body contains a JSON representation of the chunk upload info, including a id property (7890 in this sample request) that you can use for subsequent requests.

Example request and response

Copy

Example request

   -X POST 'https://{hostname}/dacfs_upload1/rest/uploads/7890?returnEntity=true' \
   -H 'Accept: application/json' \
   -H 'X-Kiteworks-Version: 15' \
   -H 'Authorization: Bearer {access_token}' \
   -F 'compressionMode=NORMAL' \
   -F 'compressionSize=1024' \
   -F 'originalSize=1024' \
   -F 'index=1' \
   -F 'content=@/tmp/MyNewFile.txt_chunk_1'
Copy

Example response (chunk)

{
    "error": "OK",
    "totalSize": 2048,
    "timestamp": "2020-05-15T08:11:07Z",
    "uri": "dacfs_upload1/rest/uploads/7890",
    "userId": 1,
    "lastTimestamp": "2020-05-15T08:11:07Z",
    "uploadedSize": 1024,
    "clientName": "OAuth Playground",
    "fileUrl": "",
    "location": "{hostname}",
    "totalChunks": 2,
    "uploadedChunks": 1,
    "completeOk": 0,
    "svrUploadTime": 0,
    "id": 7890,
    "replaceId": null,
    "backend": "acfs"
}
Copy

Example response (final chunk)

{
    "locked": false,
    "description": "",
    "created": "2020-05-15T06:25:16Z",
    "deleted": false,
    "clientModified": null,
    "fingerprint": "Generating...",
    "userId": 1,
    "modified": "2020-05-15T09:30:14Z",
    "clientCreated": null,
    "name": "MyNewFile.txt",
    "overriddenExpire": false,
    "expire": null,
    "mime": "text/plain",
    "permDeleted": false,
    "parentId": 1234,
    "type": "f",
    "id": 1240,
    "size": 2048
}

Send email

HTTP Method

Request URL
PUT

https://{base_url}/rest/mail/{mail_id}/actions/sendFile

To send the email, make a PUT request to https://{base_url}/rest/mail/{mail_id}/actions/sendFile to update the draft value to false. You can also make any other changes to the email configuration - subject, body, recipients, etc. Just keep in mind that once the email is no longer a draft, it is immediately sent.

Example request

Copy

Example request

curl -X PUT "https://{base_url}/rest/mail/{mail_id}/actions/sendFile?returnEntity=True" \
  -H "X-Accellion-Version: 28" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "files": ["UPLOADED_FILE_ID"],
        "draft": "false",
        "uploading": 0
      }'

Python code sample

In this code sample, the following operations are included:

  • Creating an email draft

  • Initiating multi-chunk upload

  • Proceeding with the upload of chunks

  • Sending the email after upload has been completed