Upgrade Guides

Update Mail & Email to UUID (v20 to v21+)

When Kiteworks API moved from v20 to v21, all mail, email, and package IDs changed from sequential integers to Universally Unique Identifier (UUID) strings. If you built your integration against v20 or earlier, update every place your code stores, constructs, or compares these IDs.

Who Is Affected

This guide applies only if you built your integration against API v20 or earlier. The ID format is controlled by the X-Accellion-Version header — once you send v21 or higher (including v28), all mail and email IDs are UUID strings.

If you are unsure which API version your integration targets, see Check Your API Version before continuing.

What Changed

In API v21, all ID fields for mail messages, email packages, shared mailboxes, and Data Leak Investigator (DLI) mail changed from sequential integers to UUID strings. This affects path parameters, query parameters, request body fields, and response body fields.

json 
// Old (v20 and earlier)
{ "id": 9876, "emailPackageId": 5432, "actor": { "id": 100 } }

// New (v21 and later, including v28)
{ "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "emailPackageId": "b2c3d4e5-...", "actor": { "id": "c3d4e5f6-..." } }

Step 1 — Audit Your Code

Search your source code for every place that constructs mail URLs or assigns email IDs from integer literals:

bash 
# Find integer ID usage in mail URL construction
grep -rn "rest/mail/[0-9]" ./src
grep -rn "email_id\s*=\s*[0-9]" ./src
grep -rn "int(.*email" ./src

Step 2 — Update Path Parameters

The following path parameters now require UUID strings instead of integers:

Parameter Example Endpoint Notes
{id} GET /rest/mail/{id} Mail message ID — now UUID
{emailId} PATCH /rest/mail/{emailId} Email ID — now UUID
{attachment_id} GET /rest/mail/{id}/attachments/{attachment_id} Attachment ID — now UUID
{userId} DELETE /rest/admin/mail/actions/withdrawFiles/users/{userId} User ID — becomes UUID in v22, not v21. If upgrading only to v21, this parameter remains an integer. See Update Users to UUID (v21 to v22+) when you proceed to v22.
python 
# Old — integer email ID in URL
email_id = 9876
url = f"{base_url}/rest/mail/{email_id}"

# New v28 — UUID string
email_id = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
url = f"{base_url}/rest/mail/{email_id}"

Step 3 — Update Query Parameters

The following query parameters now accept UUID strings instead of integers:

Parameter How to Update
emailId:in Re-fetch email UUIDs via GET /rest/mail, then replace any stored integer IDs with the returned UUID strings before passing them to this parameter.
email Re-fetch the email UUID via GET /rest/mail/{id}. If you stored the integer email ID for filtering, replace it with the UUID string from the same endpoint.
emailId Re-fetch the email UUID via GET /rest/mail/{id}, then replace the stored integer with the UUID string.
attachmentId:in Re-fetch attachment UUIDs via GET /rest/mail/{id}/attachments, then replace stored integers with the returned UUID strings.

Step 4 — Update Request Body Fields

The following request body fields now require UUID strings:

Field Endpoint Notes
parentEmailId POST /rest/mail/actions/sendFile Parent email ID — now UUID string
sharedMailboxId POST /rest/admin/sharedMailboxes Shared mailbox ID — now UUID string
memberIds PATCH /rest/admin/sharedMailboxes/{id}/members Array of user UUID strings
destinationFolderId PATCH /rest/mail/{id}/actions/move Destination folder ID — now UUID string
retainToUser DELETE /rest/admin/users/{id} Recipient user ID — now UUID string
userId Various admin mail actions User ID — now UUID string
json 
// Old
{ "parentEmailId": 5432, "memberIds": [100, 200] }

// New v28
{ "parentEmailId": "b2c3d4e5-...", "memberIds": ["c3d4e5f6-...", "d4e5f6a7-..."] }

Step 5 — Update Response Parsing

Update any code that stores, compares, or type-checks ID fields from mail and email API responses. These fields now return UUID strings:

Field Appears In
id All mail and email package objects
emailPackageId Email send responses
actor.id Mail activity and audit entries
parentEmailId Reply and thread references
package.id Package metadata in mail responses
emailReturnReceipt[].userId Return receipt recipient list
outgoingTransferringIds Transfer state tracking
members[].id Shared mailbox member list
python 
# Old — IDs were integers
email_id = email["id"]           # was: 9876
pkg_id   = email["emailPackageId"]  # was: 5432

# New v28 — IDs are UUID strings
email_id = email["id"]           # now: "a1b2c3d4-..."
pkg_id   = email["emailPackageId"]  # now: "b2c3d4e5-..."

See All Affected Endpoints

This migration affects 7 endpoints across Mail and Shared Mailbox resources, with 11 individual field-level changes. Use the interactive API Changelog to see the full list — View Mail & Email changes (v20→v21) ↗

Code Samples

Send a file via mail (before and after):

python — before (v20) 
# Before — v20, integer IDs
data = {
    "recipients": ["colleague@example.com"],
    "subject":    "Quarterly Report",
    "folderId":   6789,       # integer folder ID
}
resp = requests.post(
    f"{base_url}/rest/mail/actions/sendFile",
    headers={"Authorization": f"Bearer {token}", "X-Accellion-Version": "20"},
    json=data,
)
email_id = resp.json()["id"]   # integer
python — after (v28) 
# After — v28, UUID strings
data = {
    "recipients": ["colleague@example.com"],
    "subject":    "Quarterly Report",
    "folderId":   "6a2b3c4d-e5f6-7890-abcd-ef1234567890",   # UUID string
}
resp = requests.post(
    f"{base_url}/rest/mail/actions/sendFile",
    headers={"Authorization": f"Bearer {token}", "X-Accellion-Version": "28"},
    json=data,
)
email_id = resp.json()["id"]   # UUID string

Retrieve an email attachment:

bash 
# Before — integer IDs
curl -s -H "Authorization: Bearer $TOKEN" \
     -H "X-Accellion-Version: 20" \
     "https://your-instance.kiteworks.com/rest/mail/9876/attachments/111"

# After — UUID IDs
curl -s -H "Authorization: Bearer $TOKEN" \
     -H "X-Accellion-Version: 28" \
     "https://your-instance.kiteworks.com/rest/mail/a1b2c3d4-e5f6-7890-abcd-ef1234567890/attachments/c3d4e5f6-e5f6-7890-abcd-ef1234567890"

Next Steps

After completing all five steps, test your integration against a v21+ (or v28) instance and verify that mail operations return UUID strings in all ID fields.