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

> How to update your Kiteworks API integration to use UUID strings instead of integer IDs for Mail and Email endpoints — required when upgrading to API v28 from v20 or earlier.

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](upgrade-check-version.html) 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 Copy

```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 Copy

```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+)](upgrade-uuid-users.html) when you proceed to v22. |

python Copy

```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 Copy

```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 Copy

```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) ↗](changelog.html?from=20&to=21&tags=mail,sharedMailbox)

## Code Samples

**Send a file via mail (before and after):**

python — before (v20) Copy

```python
# 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) Copy

```python
# 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 Copy

```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.

- [Update Users to UUID (v21 to v22+) →](upgrade-uuid-users.html) Upgrade user IDs if you built your integration against v21 or earlier — including `{userId}` on mail endpoints.
- [Update Files & Folders to UUID (v18 to v19+) →](upgrade-uuid-files-folders.html) Upgrade file and folder IDs if you built against v18 or earlier.
- [Upgrade to API v28 →](upgrade-api-v28.html) Apply all remaining breaking changes to reach the current API version.